Руководство по дизайн-токенам

Обзорное видео

Лучшие практики из видео 📹

Памятка для дизайнера

Figma как источник правды

Figma является единственным источником правды для дизайн-токенов. Все изменения должны начинаться здесь и затем распространяться в код.

Настройка Figma

1. Создайте отдельную страницу "🎨 Design Tokens"
2. Используйте Styles для определения токенов
3. Следуйте конвенции именования:
   • Цвета: tz/color/[категория]/[название]
   • Отступы: tz/spacing/[размер]
   • Типографика: tz/typography/[стиль]

Трюки для эффективной работы в Figma

• Используйте Auto Layout для демонстрации отступов
• Создайте компонент-витрину для каждой категории токенов
• Добавьте описания к стилям для автоматической документации
• Используйте Variables для динамических значений
• Создайте темную тему через Variables

Категории токенов и префиксы

Реализация в нашем проекте

Структура токенов

В проекте используется три уровня дизайн-токенов:

1. Пакет @teez/design-tokens (TODO)

// package.json
{
  "name": "@teez/design-tokens",
  "version": "1.0.0",
  "description": "Teez Design System Tokens",
  "repository": "https://github.com/teez/design-tokens.git",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

// src/tokens/colors.ts
export const colors = {
  primary: '#B4FF87',
  secondary: '#7281A1',
  gray: '#667085',
  black: '#2C3344'
} as const;

// src/css/variables.css
:root {
  --teez-primary: #B4FF87;
  --teez-secondary: #7281A1;
  --teez-gray: #667085;
  --teez-black: #2C3344;
}

2. Mantine Theme

// src/app/ui/mantine-theme.config.ts
const theme: MantineThemeOverride = {
    // Цветовые палитры
    colors: { 
        teezGray: ['#eff4fe', '#e3e6ed', ...],
        teezGreen: ['#e2ffd2', '#dbffc7', ...],
        secondaryColor: ['#7281A1', ...],
        neutral: ['#f4f6fb', ...]
    },
    // Брейкпоинты
    breakpoints: {
        xl: '1200px',
        lg: '1024px',
        md: '768px',
        sm: '576px',
        xs: '0px'
    },
    // Размеры шрифтов
    fontSizes: {
        xs: rem(12),
        sm: rem(13),
        md: rem(15),
        lg: rem(20),
        xl: rem(24)
    }
};

3. CSS Custom Properties

/* Mantine автоматически создает CSS-переменные */
:root {
    /* Цвета */
    --mantine-color-teezGreen-7: #B4FF87;
    --mantine-color-teezGray-8: #667085;
    
    /* Отступы */
    --mantine-spacing-xs: 8px;
    --mantine-spacing-sm: 12px;
    --mantine-spacing-md: 16px;
    
    /* Радиусы */
    --mantine-radius-sm: 6px;
    --mantine-radius-md: 12px;
}

Установка и использование (TODO)

# .npmrc
@teez:registry=https://npm.pkg.github.com

# Установка пакета
npm install @teez/design-tokens

Использование в TypeScript:

// Импорт токенов
import { colors } from '@teez/design-tokens/tokens';
import { mantineTheme } from '@teez/design-tokens/theme/mantine';

// Использование в компоненте
const useStyles = createStyles((theme) => ({
    button: {
        backgroundColor: theme.colors.teezGreen[7],
        padding: theme.spacing.md
    }
}));

Использование в CSS:

/* Импорт переменных */
@import '@teez/design-tokens/css/variables.css';

/* Использование в стилях */
.button {
    color: var(--teez-primary);
    margin: var(--mantine-spacing-md);
}

Структура пакета (TODO)

@teez/design-tokens/
├── src/
│   ├── tokens/          # Токены в TypeScript
│   │   ├── colors.ts    # Цветовые токены
│   │   ├── spacing.ts   # Отступы
│   │   └── index.ts     # Общий экспорт
│   ├── css/            # CSS переменные
│   │   └── variables.css
│   └── theme/          # Конфигурации тем
│       └── mantine.ts  # Для Mantine
└── package.json

Процесс разработки

Текущий процесс

1. Токены определяются в mantine-theme.config.ts
2. CSS-переменные используются через Mantine или напрямую
3. Компоненты используют тему через createStyles или CSS Modules

Планируемый процесс (TODO)

1. Токены определяются в @teez/design-tokens
2. Изменения проходят через PR в репозитории дизайн-токенов
3. Автоматическая публикация в GitHub Packages при релизе
4. Обновление зависимости в основном проекте

Лучшие практики

1. Используйте theme из Mantine для компонентов через createStyles или sx prop
2. Для CSS Modules используйте CSS-переменные (--mantine-* или --teez-*)
3. Следуйте конвенции именования Mantine для консистентности
4. Добавляйте новые цвета в theme.colors для доступа через тему
5. Используйте rem() хелпер для размеров в теме
6. После внедрения пакета @teez/design-tokens, импортируйте токены из него

Инструменты

• Mantine Theme для основной темизации
• CSS Modules для компонентного стилизации
• PostCSS для обработки CSS-переменных
• GitHub Packages для хостинга пакета дизайн-токенов
• GitHub Actions для автоматической публикации

Префиксы для продуктов Teez

Решение проблем

• Стили не применяются? Проверьте импорт '@mantine/core/styles.css'
• CSS-переменные не работают? Убедитесь что компонент обернут в MantineProvider
• Конфликты стилей? Используйте специфичные селекторы в CSS Modules
• Проблемы с установкой @teez/design-tokens? Проверьте настройки .npmrc и токены GitHub

Полезные ресурсы

• Mantine Theme Documentation
• Mantine CSS Modules Guide
• PostCSS Documentation

Внесение изменений

1. Новые токены добавляйте в mantine-theme.config.ts
2. CSS-переменные определяйте в глобальных стилях
3. Обновляйте документацию при добавлении новых токенов
4. Проверяйте консистентность с существующими компонентами