Документация стилей: создание style guide и component library

Зачем нужен Style Guide? 🎨

Представьте, что ваш CSS-код — это город. Без чётких правил он превратится в хаотичные трущобы, где каждый строит как хочет. Style Guide — это генплан, который сохраняет порядок, помогает команде работать слаженно и ускоряет разработку в 2–3 раза.

Основные преимущества:

• Единый визуальный язык для всех разработчиков и дизайнеров
• Снижение количества багов из-за неконсистентности
• Быстрый онбординг новых членов команды

💡 Совет от Данилы Бежина: "Style Guide — это живой документ. Начните с малого и расширяйте его по мере роста проекта. Идеальный вариант — привязать его к процессу code review."

Создаём базовый Style Guide 🧱

Разберём ключевые разделы, которые должны быть в любом руководстве по стилям.

1. Цветовая палитра 🌈

Не просто перечисляем цвета, а даём им осмысленные имена и контекст использования:

:root {
  /* Основные цвета */
  --color-primary: #3a86ff;
  --color-secondary: #8338ec;

  /* Функциональные цвета */
  --color-success: #06d6a0;
  --color-danger: #ef476f;

  /* Нейтральные оттенки */
  --color-gray-100: #f8f9fa;
  --color-gray-900: #212529;
}

⚠️ Важно: Всегда используйте CSS-переменные для цветов. Это позволит менять тему одним редактированием.

2. Типографика и вертикальный ритм ✒️

Зафиксируйте правила для текста:

:root {
  /* Базовые настройки */
  --base-font-size: 16px;
  --line-height: 1.5;

  /* Шрифты */
  --font-primary: 'Inter', sans-serif;
  --font-mono: 'Roboto Mono', monospace;

  /* Масштаб типографики */
  --text-xs: 0.75rem;
  --text-lg: 1.125rem;
}

Добавьте таблицу стилей для заголовков:

Component Library: от атомов к организмам ⚛️

Atomic Design — лучшая методология для создания библиотеки компонентов. Разберём на примере кнопки:

1. Базовый атом (Atom)

.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border: none;
  cursor: pointer;
  font-family: var(--font-primary);
  transition: all 0.2s ease;
}

2. Модификаторы (Variants)

/* Размеры */
.button--sm {
  padding: 0.5rem 1rem;
  font-size: var(--text-xs);
}

.button--lg {
  padding: 1rem 2rem;
  font-size: var(--text-lg);
}

/* Стили */
.button--primary {
  background: var(--color-primary);
  color: white;
}

.button--outline {
  background: transparent;
  border: 2px solid var(--color-primary);
}

3. Состояния (States)

.button:hover {
  transform: translateY(-1px);
}

.button:active {
  transform: translateY(0);
}

.button:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

Документируем компоненты 📚

Используйте комментарии в формате CSSDOCS для автоматической генерации документации:

/**
 * @name Button
 * @description Интерактивный элемент для действий пользователя
 * 
 * @state :hover - Эффект при наведении
 * @state :disabled - Неактивное состояние
 * 
 * @variant .button--primary - Основной стиль
 * @variant .button--outline - Контурный стиль
 */

🌟 Pro-совет: Интегрируйте Storybook или Fractal для интерактивного просмотра компонентов с живыми примерами.

Инструменты для автоматизации 🛠️

1. Stylelint — линтер для проверки соответствия Style Guide
2. PostCSS — генерация префиксов и оптимизация CSS
3. Theo от Salesforce — конвертация стилей в форматы для разных платформ

Пример конфига Stylelint:

{
  "extends": "stylelint-config-standard",
  "rules": {
    "color-hex-case": "lower",
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]+$",
    "value-keyword-case": "lower"
  }
}

Как поддерживать актуальность? 🔄

1. Версионирование — используйте семантическое версионирование (SemVer) для изменений

2. Чеклист обновлений — при изменении компонента проверяйте:

• Соответствие документации
• Обратную совместимость
• Примеры использования

3. Регулярные аудиты — раз в квартал проверяйте устаревшие компоненты

Вот и всё! Теперь ваш CSS — не просто код, а продуманная дизайн-система. 🎉 Помните: чем строже правила, тем больше свободы для творчества!