Сравни способы задокументировать компонент и объясни, когда выбирать каждый вариант.

Документировать компонент можно на нескольких уровнях — от типов до живой витрины. На практике их сочетают.

Типы (TypeScript) — базовый уровень

type ButtonProps = {
  /** Визуальный вариант кнопки */
  variant?: 'primary' | 'ghost';
  onClick: React.MouseEventHandler<HTMLButtonElement>;
};

• Плюсы: документация не устаревает (компилятор следит), видна в IDE; JSDoc-комментарии над полями всплывают в подсказках.
• Минусы: не показывает, как компонент выглядит и когда его применять.
• Выбирать: всегда, это фундамент.

Storybook — живая витрина

Истории для каждого состояния (варианты, ошибки, загрузка), интерактивные контролы, автодокументация props из типов.

• Плюсы: дизайнеры и продакт видят компонент; используется как «песочница» разработки; можно прогонять a11y- и визуальные тесты.
• Минусы: инфраструктура, поддержка историй.
• Выбирать: дизайн-системы и UI-киты, командные проекты.

Тесты как документация

Testing Library-тесты описывают поведение на языке пользователя («кликнул — увидел»), не устаревают, потому что падают. Выбирать: всегда для нетривиального поведения; они дополняют, а не заменяют витрину.

README/MDX-страницы

Когда и зачем использовать компонент, ограничения, миграции, примеры композиции. Storybook Docs (MDX) объединяет текст и живые примеры. Выбирать: публичные библиотеки, сложные компоненты с неочевидными правилами.

Что не работает

Отдельные wiki-страницы, оторванные от кода: устаревают за месяц. Документация должна жить рядом с исходником.

Коротко для собеседования

Базис — типы + JSDoc (не устаревают, видны в IDE); витрина состояний и props — Storybook (нужен для дизайн-систем); поведение — тесты RTL; «когда и зачем применять» — README/MDX рядом с кодом. Внешние wiki без связи с кодом — антипаттерн.