Перейти к основному содержимому

Интеграция дизайн-системы в существующие проекты

Регламент не требует мгновенного рефакторинга всего UI, но запрещает ухудшать текущее состояние. Внедрение дизайн-системы — итеративный процесс с чёткими правилами для нового и старого кода.

Проекты без дизайн-системы​

MUST​

  1. Добавить минимальный централизованный слой:

    • Файл UI-констант или набор CSS-переменных
    • Базовый компонент Icon
    • Минимальный набор токенов

  2. Новый UI-код не содержит захардкоженных значений:

    • Все значения берутся из централизованного слоя

Правило нового кода​

MUST​

Весь новый UI-код обязан:

  1. Использовать дизайн-токены для всех стилевых значений
  2. Использовать единый компонент Icon (если есть иконки)
  3. Не добавлять захардкоженные значения

Примеры​

/* ✅ Правильно */
import { Button } from '@/shared/ui/Button';

<Button variant="primary">Отправить</Button>

/* ❌ Неправильно */
<button style={{
  background: '#1b1b1b',
  color: '#fff',
  padding: '12px 24px'
}}>
  Отправить
</button>

Правило бойскаута (по касанию)​

Временные отклонения (MVP / небольшие проекты)​

MAY​

Допускается на старте:

  1. Не выносить токены в отдельный пакет:

    • Локальный файл с UI-константами

  2. Использовать ограниченный набор CSS-переменных:

:root {
  --color-primary: #3b82f6;
  --color-text: #1b1b1b;
  --space-m: 16px;
}
  1. Простой компонент Icon без генерации типов:
export const Icon = ({ name, ...props }) => {
  return <img src={`/icons/${name}.svg`} {...props} />;
};
  1. Отсутствие SVG pipeline:
    • Прямое использование SVG-файлов через компонент Icon

MUST​

Обязательные ограничения:

  1. Запрещено хаотичное использование "магических" значений:

    • Все значения централизованы в одном месте

  2. Новые захардкоженные значения не добавляются:

    • Даже "на время" или "только для этого экрана"

  3. Упрощения не ухудшают консистентность интерфейса

Условия возврата к строгим правилам​

Возврат к основным правилам необходим при:

  • Росте проекта или команды
  • Появлении требований к темам (light/dark)
  • Планировании ребрендинга
  • Использовании UI в нескольких подпроектах
  • Увеличении количества повторяющихся компонентов

Управление изменениями​

MUST​

  1. Изменения токенов и иконок согласуются с дизайном:

    • Нельзя добавлять токены без согласования

  2. Изменения поставляются как версия (semver) с changelog:

## [2.1.0] - 2025-02-13

### Added

- Новый токен `color.bg.overlay`

### Changed

- `button.primary.bg` теперь использует `color.brand.600`

### Deprecated

- `color.legacy.blue` — использовать `color.brand.primary`

SHOULD​

  1. Deprecated-токены объявляются заранее:

    • Окно миграции минимум 2 релиза

  2. Критичные изменения проходят через экспериментальную стадию:

    • Флаг experimental: true в конфиге