7 разделов документации компонента дизайн-системы: разбор страницы, которую действительно открывают

    16 ноября 2026 г.
    8 мин чтения
    Автор: Arden Vaskerby
    Поделиться этой статьей
    Видео: 7 разделов документации компонента дизайн-системы: разбор страницы, которую действительно открывают

    Вторник, одиннадцать утра. Фронтенд-разработчик собирает фильтры для таблицы заказов, и ему нужен выпадающий список с множественным выбором. Он открывает страницу компонента 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, дополнительно ловят незаметные изменения внешнего вида.

    Нужно ли описывать токены на странице компонента? Достаточно перечислить, какие токены компонент использует, и сослаться на отдельную страницу токенов. Если описывать значения цветов и отступов прямо на странице компонента, при смене темы или палитры придётся править десятки страниц вместо одной.

    И о том, когда полную страницу из семи разделов писать не нужно. Если компонент экспериментальный и его поведение ещё меняется каждую неделю, хватит назначения, статуса «эксперимент» и контакта ответственного. Если дизайн-систему ведут два человека для одного продукта и сидят рядом с разработчиками, подробная документация может стоить дороже, чем разговор за соседним столом.

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

    Похожие статьи

    9 мин чтения

    Одно правило порога бесплатной доставки: доплаты должны оплатить доставку, которую вы перестали брать

    Порог бесплатной доставки чаще выбирают по среднему чеку, хотя решает другое: сколько людей доплатят до порога и сколько маржи принесут их доплаты. Разбираем одну формулу, условный пример, прогресс-бар в корзине и проверку A/B-тестом.

    15 ноября 2026 г.
    9 мин чтения

    Маркетинг по Jobs To Be Done ищет ситуацию, которую сегмент не видит

    Демография объясняет, кто покупатель, но не почему он покупает. JTBD-маркетинг ищет ситуацию выбора: как нащупать работу продукта, чем её обычно подменяют и что видно на двух собирательных историях о планировщике задач и B2B-аналитике.

    4 января 2026 г.
    8 мин чтения

    Фреймворк трёх запасов: как креативной команде планировать производство, чтобы частота показов в Meta Ads не выжигала рекламу

    Креативная усталость в Meta Ads обычно обсуждается как проблема медиабайера, хотя решается она в производстве креатива. Показываем фреймворк трёх запасов, расчёт числа креативов от бюджета и аудитории и место ИИ-вариаций в этом плане.

    18 ноября 2026 г.