Вторник, одиннадцать утра. Фронтенд-разработчик собирает фильтры для таблицы заказов, и ему нужен выпадающий список с множественным выбором. Он открывает страницу компонента Select в документации дизайн-системы. Там красивая обложка, три скриншота, абзац про «единообразный пользовательский опыт» и ссылка на Figma. Нет ответа ни на один из его вопросов: подходит ли Select для множественного выбора, как он ведёт себя внутри узкой ячейки, что происходит, когда вариантов больше пятидесяти. Через десять минут в общем чате появляется сообщение: «Кто знает, можно Select в таблицу?»
Такая страница не пустая. Её делали старательно, просто для другого читателя: того, кто хочет полюбоваться компонентом, а не применить его. Ниже разобрана страница того же Select, переписанная под тех, кто её действительно открывает, по семи разделам. Порядок разделов совпадает с порядком вопросов, которые возникают у человека в работе.
Разделы 1-3: назначение, ограничения и анатомия
Первый раздел, назначение, укладывается в два-три предложения. Что делает компонент и в какой ситуации его берут. Для Select это звучит так: «Выбор одного значения из списка от 5 до 30 вариантов, когда места на экране мало, а сами варианты пользователю заранее известны». В этой фразе уже три ограничения, и каждое отсекает неправильные применения.
Второй раздел почти всегда пропускают, хотя он экономит больше всего времени: когда компонент не использовать. Для Select такой список выглядит примерно так. Вариантов меньше пяти: лучше группа переключателей, все варианты видны сразу. Вариантов больше 30 или пользователь их не знает: нужен комбобокс с поиском. Нужно выбрать несколько значений: используйте компонент множественного выбора, Select для этого не предназначен. Выбор запускает действие, а не задаёт значение: это меню, у него другая семантика и другое поведение с клавиатуры. Каждый пункт ссылается на страницу альтернативы.
Именно этот раздел ответил бы на вопрос разработчика из вступления. Он сэкономил бы ему десять минут, а команде дизайн-системы ещё один разговор в чате.
Третий раздел, анатомия, разбирает компонент на части с номерами: подпись, поле, значок раскрытия, выпадающая панель, пункт списка, вспомогательный текст, текст ошибки. Каждой части даётся имя, которое совпадает с именем слоя в Figma и с именем элемента или слота в коде. Это мелочь, на которой держится весь хендофф: когда дизайнер говорит «поправь вспомогательный текст», а разработчик видит в коде helperText, они понимают друг друга без перевода.
Анатомию удобнее всего показывать схемой с выносками, а не текстом. Но под схемой стоит перечислить, какие части обязательны, а какие нет: у Select обязательны подпись, поле и панель, вспомогательный текст и иконка слева необязательны.
Разделы 4-5: варианты, состояния и свойства
Четвёртый раздел описывает варианты и состояния. Варианты отличаются по назначению или размеру: стандартный и компактный для таблиц, с иконкой и без. Состояния описывают взаимодействие: по умолчанию, при наведении, в фокусе, раскрыт, выбран, с ошибкой, недоступен, только для чтения. Для каждого состояния нужен живой пример и одна строка о том, когда оно возникает. Отдельно стоит показать крайние случаи: очень длинное значение, которое не помещается в поле, пустой список, список при загрузке, панель у нижнего края экрана, которая должна раскрыться вверх.
Пятый раздел самый технический и самый полезный для разработчиков: таблица свойств. Лучше всего она работает, когда в одной строке стоят свойство компонента в Figma, свойство в коде, допустимые значения и значение по умолчанию.
| Свойство в Figma | Свойство в коде | Значения | По умолчанию |
|---|---|---|---|
| Size | size | default, compact | default |
| State | состояние вычисляется | default, hover, focus, error, disabled | default |
| Has helper text | helperText | строка или пусто | пусто |
| Has leading icon | leadingIcon | иконка из набора или пусто | пусто |
| Label | label | строка, обязательно | нет |
Обратите внимание на вторую строку. В Figma состояние приходится задавать вручную, а в коде оно вычисляется из поведения пользователя и атрибутов вроде disabled. Если не написать это явно, разработчик начнёт искать проп state и, не найдя, сделает свой. Расхождения между свойствами в Figma и в коде неизбежны, и честная таблица делает их видимыми.
Ещё одна деталь раздела: какие сочетания свойств запрещены. Компактный размер с вспомогательным текстом, например, ломает высоту строки таблицы, ради которой компактный вариант и существует. Одна строка «не сочетать» убережёт от этого лучше, чем любой код-ревью.
Разделы 6-7: доступность и правила текста
Шестой раздел, доступность, отвечает на вопросы, которые разработчик задаст обязательно, а дизайнер, скорее всего, нет. Какая роль у компонента и его частей. Как он работает с клавиатуры: открытие по Enter, пробелу или стрелке вниз, перемещение стрелками, выбор по Enter, закрытие по Escape с возвратом фокуса в поле, поиск по первой букве. Что произносит скринридер при фокусе и при выборе значения. Как связаны подпись, вспомогательный текст и текст ошибки с полем.
Здесь же стоит указать, на какие критерии WCAG опирается компонент, и что из этого обеспечивает сам компонент, а что остаётся на совести того, кто его использует. Например, Select сам связывает подпись с полем, но если продуктовая команда передаст пустую подпись, никакая разметка не спасёт.
Седьмой раздел про текст. Как писать подпись: существительное или короткая фраза без двоеточия, «Страна доставки», а не «Выберите страну». Как писать плейсхолдер, если он вообще нужен. Как писать текст ошибки: что не так и как исправить, «Выберите страну доставки, чтобы рассчитать стоимость». Как сортировать варианты: по алфавиту, по частоте, по логике предметной области. Как обрезать длинные значения и показывать их полностью.
Правила текста выглядят второстепенными, пока в одном продукте не появляются три Select с подписями «Страна», «Выберите страну:» и «Укажите страну проживания». Каждый в отдельности приемлем, вместе они выдают продукт, который собирали разные люди.
Где хранить документацию и кто её обновляет
Документация компонента живёт минимум в двух местах. В Figma у компонента есть поле описания и ссылка на документацию: дизайнер видит их прямо в панели свойств, не уходя из макета. Туда стоит писать одну фразу назначения и ссылку на полную страницу. В коде документацию обычно собирают в Storybook: истории показывают живые состояния, а страницы в формате MDX несут текст. Сверху часто ставят отдельный сайт документации на Zeroheight, Supernova или самописном движке, который собирает в одном месте и фреймы из Figma, и истории из Storybook.
Главное правило: у каждого раздела один источник. Таблица свойств генерируется из кода или поддерживается в одном месте и встраивается в остальные. Если одну и ту же таблицу ведут вручную в Figma, в Storybook и на сайте, через три месяца у вас три разных таблицы.
Иллюстративный мини-кейс. Продуктовая команда из 12 человек обнаружила в коде три реализации выпадающего списка: собственно Select из дизайн-системы, самописный вариант с поиском и форк Select с множественным выбором. Причина оказалась простой: на странице компонента не было раздела о том, когда его не использовать, и ссылок на альтернативы.
Каждый разработчик, не найдя ответа, делал своё. Команда дизайн-системы добавила второй раздел, выпустила комбобокс с поиском как отдельный компонент и описала множественный выбор. За два квартала две лишние реализации заменили, а количество вопросов про выпадающие списки в чате, по подсчёту самой команды, упало примерно втрое.
Ответственность распределяется так: при изменении компонента обновление документации входит в критерии готовности задачи. Не отдельной задачей «потом», а частью той же, иначе документация начинает отставать от кода с первого спринта.
Как измерить полноту документации
Субъективная оценка «документация у нас неплохая» ничего не говорит о том, где именно дыры. Помогают три простых показателя.
Полнота страницы = заполненные обязательные разделы / 7 × 100%
Покрытие системы = компоненты с полнотой 100% / все опубликованные компоненты × 100%
Свежесть = компоненты, чья документация обновлена после последнего
изменения компонента в коде / все опубликованные компоненты × 100%
Раздел считается заполненным, если в нём есть содержание по существу, а не заглушка «скоро будет». Условный пример: в системе 48 опубликованных компонентов, у 30 заполнены все семь разделов. Покрытие равно 30 / 48, то есть 62,5%. При этом у 36 компонентов документация обновлялась после последней правки в коде, свежесть 75%. Значит, дюжина страниц уже описывает поведение, которого больше нет, и это хуже, чем отсутствие страницы: пустая страница хотя бы не вводит в заблуждение.
Полезно смотреть и на то, какие разделы пустуют чаще всего. Почти всегда это второй и шестой: ограничения и доступность. Если в квартальном плане команды дизайн-системы есть одна задача по документации, начать стоит именно с них.
Свежесть удобно считать автоматически: сравнивать дату последнего коммита в папке компонента с датой последнего изменения его страницы документации. Это полчаса работы для разработчика и честная цифра каждую неделю.
Что ещё спрашивают про документацию компонентов
Сколько времени уходит на документацию одного компонента? Для компонента средней сложности первая страница обычно занимает от 4 до 8 часов вместе с примерами и согласованием с разработчиками. По готовому шаблону следующие страницы пишутся примерно вдвое быстрее, потому что структура и формулировки уже отработаны.
Как держать примеры на странице в актуальном состоянии? Вместо скриншотов встраивать живые примеры: истории из Storybook или фреймы Figma через встраивание. Скриншот устаревает с первой правкой компонента, а встроенный пример меняется вместе с ним. Визуальные регрессионные тесты, например Chromatic, дополнительно ловят незаметные изменения внешнего вида.
Нужно ли описывать токены на странице компонента? Достаточно перечислить, какие токены компонент использует, и сослаться на отдельную страницу токенов. Если описывать значения цветов и отступов прямо на странице компонента, при смене темы или палитры придётся править десятки страниц вместо одной.
И о том, когда полную страницу из семи разделов писать не нужно. Если компонент экспериментальный и его поведение ещё меняется каждую неделю, хватит назначения, статуса «эксперимент» и контакта ответственного. Если дизайн-систему ведут два человека для одного продукта и сидят рядом с разработчиками, подробная документация может стоить дороже, чем разговор за соседним столом.
Если компонент используется в одном месте и вряд ли появится где-то ещё, возможно, ему вообще не место в системе. Документация окупается там, где компонент живёт долго, используется многими и читается людьми, которые не могут просто спросить автора.
