Документация и управление системой: страница компонента, версии, вклад

Документация дизайн-системы объясняет, когда и как брать каждый компонент. Управление — правила её изменений: статусы, версии по SemVer, устаревание, вклад.

Система, которой нельзя воспользоваться, не существует

Хорошую кнопку можно сделать за час. Чтобы ею пользовались другие, нужен ещё день: описать, когда брать и как. Без описания человек либо спрашивает у автора, либо делает свою кнопку. Дизайн-система живёт ровно настолько, насколько понятна её документация.

Вторая половина урока про то, что бывает после запуска. Система не заканчивается на релизе: в неё нужно вносить изменения, и у людей, которые ею пользуются, должны быть гарантии. О них договариваются заранее: это называется управлением системой.

Страница компонента

Откройте в источниках страницу кнопки в GOV.UK. Это образец, и по нему видно, из чего состоит хорошее описание.

• Название и живой пример. Сразу виден компонент, а не пересказ.
• Когда использовать. Одна-две фразы о назначении: начать заявку или сохранить введённое.
• Как работает. Правила использования: подпись, выравнивание, способы подключить в разметке.
• Варианты. У кнопки GOV.UK их несколько: основная, начальная, второстепенная, предупреждающая, на тёмном фоне, недоступная, группа кнопок. У каждого свой пример и код.
• Слова. Правило подписи: писать как обычный текст с заглавной первой буквой и описывать действие («Сохранить и продолжить», а не «OK»).
• Исследование. Короткая заметка с доказательством: например, что зелёные начальные кнопки по результатам испытаний давали больше нажатий.
• Изменения. История версий и ссылка, как улучшить страницу.

Принципы, на которых это стоит:

1. Отвечайте на вопрос человека в момент работы. «Какой кнопкой это делать?», «Можно ли тут второстепенную?».
2. Показывайте, а не только рассказывайте. Живой пример и код, который можно скопировать.
3. Пишите «когда не брать». Это самая ценная часть: она предотвращает неудачные решения.
4. Храните документацию рядом с кодом. В одном репозитории, в Markdown, и тогда её меняют вместе с компонентом. У крупных систем для этого есть инструмент витрины: Storybook показывает каждый компонент во всех состояниях и служит живой документацией.

Проверьте себя: какая часть страницы компонента самая ценная?

«Когда не использовать»: она предотвращает неудачные решения. А рядом с ней живой пример и состояния.

Статус и жизненный путь

Не всё, что есть в системе, одинаково надёжно. Поэтому у каждой детали бывает статус.

• Экспериментальный. Пробуют в одном месте, правила могут измениться. У GOV.UK такой статус называется «пробный» (trial): деталь выпускают, чтобы собрать отзывы, и она стабильной становится не раньше чем через полгода без негативных отзывов. У Carbon для таких есть отдельное пространство Carbon Labs (сейчас оно только для сотрудников IBM).
• Стабильный. Принят в систему и поддерживается.
• Устаревший. Помечен: скоро уберут, замена названа.

Новую деталь не добавляют просто потому, что кто-то её захотел. GOV.UK проверяет предложения по опубликованным критериям вклада, а в Carbon новый компонент должен пройти жизненный цикл разработки и чек-лист (все категории требований должны быть выполнены, прежде чем деталь считается готовой). Простое правило для маленького проекта: выделяйте компонент в систему, когда он понадобился в третий раз. Раньше рано: вы ещё не знаете, чем будут различаться случаи.

Версии: честный договор

Если система меняется, люди, которые на ней построили, должны понимать, что их ждёт. Для этого версии нумеруют по правилу SemVer (семантическое версионирование): три числа через точки, мажорная.минорная.патч.

• Патч (1.4.2 → 1.4.3): исправление, контракт не меняется.
• Минорная (1.4.2 → 1.5.0): добавили новое, старое работает.
• Мажорная (1.4.2 → 2.0.0): изменили так, что у людей что-то сломается.

Сложность в том, что поломкой считается не только изменение кода. Переименовали токен? Мажорная. Удалили компонент? Мажорная. Сделали кнопку по умолчанию крупнее? Тоже мажорная: раскладки, подогнанные под старый размер, поедут. Поиграйте на схеме: применяйте изменения и смотрите, как меняется число.

Версия 1.4.2 (мажорная.минорная.патч, начиная с 1.4.2)

Переименовать токен color.accent в color.brandПоменять значение токена: акцент чуть темнееДобавить компонент «Подсказка»Исправить: фокус на кнопке не был виден в тёмной темеУдалить устаревший компонент «Карусель»Сделать кнопку по умолчанию крупнееПоправить опечатку в описании компонента Начать заново

Каждое изменение записывают в список изменений (changelog): дата, версия, что поменялось и что поправить пользователю. Хороший список читают перед обновлением. У страницы кнопки GOV.UK есть раздел «Recent changes» и ссылка на историю версий, у проекта GOV.UK Frontend есть файл CHANGELOG.

Как убирают деталь

Удалять деталь в один день нельзя: вы сломаете чужие страницы. Правильный порядок называется устареванием (deprecation):

1. Пометить деталь устаревшей в документации и в коде.
2. Назвать, чем её заменить, и написать, как перейти.
3. Записать в список изменений.
4. Оставить на несколько версий.
5. Удалить в следующей мажорной версии.

Проверьте себя: почему нельзя просто удалить ненужный компонент?

Те, кто на нём построил страницы, останутся с поломкой без предупреждения. Поэтому его сначала помечают устаревшим и оставляют на несколько версий.

Кто и как вносит вклад

Системой пользуются многие, и предложения приходят отовсюду. Нужно решить заранее, как они принимаются. GOV.UK описывает, как сообщество может участвовать: предложить компонент или паттерн, поделиться исследованиями, исправить страницу через GitHub; всё проверяет команда системы по критериям вклада. Кроме того там есть список планируемых компонентов, дорожная карта, чат, обсуждения и ежемесячные созвоны. У Carbon сказано «вносить вклад может любой»: код, дизайн или документацию; новые компоненты идут через жизненный цикл и чек-лист, улучшения берутся из списка, а баги исправляются отчётом и пулл-реквестом.

Для вашего проекта хватит самого простого: одного владельца (вас), списка изменений и правила устаревания, которое вы напишете ниже.

Практика

Напишите страницу-справочник кнопки главного действия вашего проекта: когда использовать и когда нет, варианты, состояния, слова, доступность, пример кода, статус и версия, список изменений и правило устаревания. Это страница, которую вы сможете показать любому, кто будет работать с вашим сайтом, включая ИИ-конструктор из части про ИИ: чем яснее у вас описаны правила, тем лучше он их соблюдает.

Что было не так с 2014 годом

В 2014 году документацию к стилям часто вели в отдельной вики или PDF, и она отставала от кода. Версий у системы не было вовсе: сайт обновляли «целиком», и никто не знал, что именно изменилось. Привычка вести список изменений и нумеровать версии по SemVer пришла в дизайн из разработки программ, и именно она отличает живую систему от разовой работы.