Toto Design System Migration Guide

This guide provides instructions for migrating existing components to use the new Toto Design System.

Why Migrate?

The Toto Design System provides several advantages:

• Consistent visual styling across all components
• Improved accessibility
• Reduced CSS duplication
• Simplified maintenance
• Better responsive behavior
• Standardized component API

Migration Steps

1. Import the Design System CSS

In your component's CSS file, import the design system at the top:

@import '../styles/toto-design-system.css';

2. Replace Hardcoded Values with Variables

Replace all hardcoded values with CSS variables:

Before:

.my-component {
  font-family: 'Open Sans', sans-serif;
  color: #333333;
  background-color: #FFFFFF;
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  transition: all 0.2s ease;
}

.my-component-button {
  background-color: #FDB813;
  color: #333333;
  padding: 8px 16px;
  border-radius: 4px;
  font-weight: 600;
}

After:

.my-component {
  font-family: var(--toto-font-family);
  color: var(--toto-neutral-dark);
  background-color: var(--toto-background);
  padding: var(--toto-spacing-md);
  border-radius: var(--toto-border-radius-md);
  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);
  transition: var(--toto-transition);
}

.my-component-button {
  background-color: var(--toto-primary);
  color: var(--toto-neutral-dark);
  padding: var(--toto-spacing-sm) var(--toto-spacing-md);
  border-radius: var(--toto-border-radius-sm);
  font-weight: var(--toto-font-weight-semibold);
}

3. Use Standardized Components

Instead of building custom UI elements, use the standardized components:

Before:

<button 
  className="my-custom-button" 
  onClick={handleClick}
  disabled={isLoading}
>
  {isLoading ? 'Loading...' : 'Submit'}
</button>

After:

import { Button } from '../components';

<Button 
  variant="primary" 
  onClick={handleClick} 
  disabled={isLoading}
>
  {isLoading ? 'Loading...' : 'Submit'}
</Button>

4. Update Class Names

Follow the Toto naming convention for CSS classes:

• Prefix all classes with toto-
• Use kebab-case for class names
• Use descriptive names that indicate component and purpose

Before:

.walletCard { ... }
.walletCardHeader { ... }
.balanceValue { ... }

After:

.toto-wallet-card { ... }
.toto-wallet-card-header { ... }
.toto-wallet-balance-value { ... }

5. Test Responsive Behavior

The design system includes responsive breakpoints:

@media (max-width: 480px) {
  .toto-hide-mobile {
    display: none;
  }
}

@media (min-width: 768px) {
  .toto-hide-desktop {
    display: none;
  }
}

Ensure your migrated components look good at all screen sizes.

Example: Complete Migration

Here's a complete example of migrating a component:

Before:

// OldComponent.jsx
import React from 'react';
import './OldComponent.css';

export const OldComponent = ({ title, children, onAction }) => {
  return (
    <div className="card">
      <div className="cardHeader">
        <h3>{title}</h3>
        <button className="actionButton" onClick={onAction}>
          Action
        </button>
      </div>
      <div className="cardBody">
        {children}
      </div>
    </div>
  );
};

/* OldComponent.css */
.card {
  background-color: white;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
  padding: 16px;
  font-family: 'Open Sans', sans-serif;
}

.cardHeader {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 16px;
}

.cardHeader h3 {
  margin: 0;
  font-size: 1.5rem;
  color: #333;
}

.actionButton {
  background-color: #337AB7;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
  font-weight: 600;
  cursor: pointer;
}

.actionButton:hover {
  background-color: #2d6da3;
}

.cardBody {
  color: #333;
}

After:

// NewComponent.jsx
import React from 'react';
import { Card, Button } from '../components';
import './NewComponent.css';

export const NewComponent = ({ title, children, onAction }) => {
  return (
    <Card
      title={title}
      headerAction={
        <Button variant="accent" onClick={onAction}>
          Action
        </Button>
      }
    >
      {children}
    </Card>
  );
};

/* NewComponent.css */
@import '../styles/toto-design-system.css';

/* Additional custom styles if needed */
.toto-card-body {
  /* Extend the default card body styles if needed */
}

Migration Checklist

• Import design system CSS
• Replace hardcoded values with CSS variables
• Use standardized components where applicable
• Update class names to follow conventions
• Test responsive behavior
• Review accessibility
• Update tests and Storybook stories

Need Help?

Refer to:

• Component Documentation
• API Reference