Документацію дизайн-системи з AI треба не «написати», а генерувати з тих самих файлів, з яких збирається продукт: токенів, пропсів компонентів і сторі. Claude робить фактичну частину (таблиці, стани, приклади коду) за хвилини, дизайнер дописує лише рішення - коли компонент брати і коли ні. А щоб документація не застаріла, її перевірка на розбіжності з кодом запускається в кожному pull request, а не «колись потім».
Нижче - що саме генерувати автоматично, покроковий процес з Claude Code, де тримати документацію і як побудувати перевірку дрейфу. Так я, Dmytro Nikolaienko, веду документацію на проєктах UX Hero і так ми її будуємо на курсі «Дизайн-система з AI».
Чому документація дизайн-системи постійно застаріває?
Бо в більшості команд вона живе окремою копією. Є Figma, є код, і є третє місце - Notion, Confluence чи сайт системи, куди хтось колись руками переписав значення токенів і список пропсів. З першого ж релізу ці три місця починають роз'їжджатись.
- Ніхто не відповідає за копію. Розробник змінив проп
variant="link"наvariant="ghost"у коді. Сторінку в Notion він не відкривав ніколи. - Оновлення не входить у «готово». Задачу закрили, коли компонент змержили, а не коли оновили документацію.
- Факти й рішення змішані. На одній сторінці і HEX-значення, які змінюються щотижня, і принципи, які не змінюються роками. Застаріле перше дискредитує друге.
Застаріла документація гірша за відсутню: вона впевнено бреше. Після двох-трьох таких випадків команда перестає її відкривати і йде питати в чат.
Що генерувати автоматично, а що писати людині?
Головний принцип: усе, що можна прочитати з файлів, генерується; усе, що є рішенням, пише людина.
| Розділ документації | Джерело правди | Хто робить |
|---|---|---|
| Таблиця токенів (назва, значення, тема) | tokens.json (W3C DTCG) | скрипт / Claude |
| Пропси, типи, значення за замовчуванням | TypeScript-інтерфейс компонента | Claude |
| Стани і варіанти з прев'ю | сторі в Storybook | Claude |
| Приклади коду | сторі / golden examples | Claude |
| Доступність (фокус, клавіатура, aria) | код + чекліст WCAG | Claude чернетка, людина перевіряє |
| Призначення одним реченням | - | Claude чернетка, людина затверджує |
| Коли використовувати і коли НЕ використовувати | продуктові рішення | дизайнер |
| Принципи і «чому так» | досвід команди | дизайнер |
Виходить приблизно 70/30: більша частина сторінки компонента - це факти, які машина знає краще за людину. Дизайнер витрачає час лише на ту третину, де потрібне судження.
Як згенерувати документацію з Claude Code: покроково
- Приведіть джерела до ладу. Токени в одному
tokens.json, у кожного компонента типізовані пропси і хоча б одна сторі на кожен стан. Якщо цього нема, документацію генерувати ні з чого - почніть з гайду зі збирання системи. - Зафіксуйте шаблон сторінки. Один Markdown/MDX-шаблон на всі компоненти: призначення, коли використовувати, коли ні, анатомія, пропси, стани, доступність, приклади. Готову структуру можна взяти з шаблону специфікації компонента.
- Згенеруйте перший компонент і вичитайте. Промпт для Claude Code:
Прочитай src/components/Button.tsx, Button.stories.tsx і tokens/tokens.json.
Заповни docs/_template.mdx для Button і збережи як src/components/Button.mdx.
Пропси, стани, токени і приклади бери ТІЛЬКИ з файлів, нічого не вигадуй.
Розділи «Коли використовувати» і «Коли НЕ використовувати» заповни чернеткою
і познач коментарем {/* TODO: review */}. Не змінюй жодних інших файлів.- Виправте шаблон, а не сторінку. Якщо щось не так у першому результаті, правте шаблон і промпт. Інакше та сама помилка повториться в 40 компонентах.
- Пройдіться по всій бібліотеці тим самим промптом і збережіть його як Claude Skill, щоб наступного разу запускати однією командою. Як це працює - у статті Claude Skills для дизайнера.
Орієнтовно: сторінка компонента вручну - це 1-2 години на збір пропсів, станів і прикладів. З генерацією дизайнер витрачає 15-20 хвилин на вичитку і розділ «коли використовувати».
Де тримати документацію: Notion, zeroheight чи Storybook?
| Де | Плюси | Мінуси | Кому |
|---|---|---|---|
| Storybook + MDX у репо | живі компоненти, оновлюється в тому ж PR, що й код; агенти читають як контекст | треба доступ до репо і базове розуміння git | командам, де дизайн доходить до коду |
| zeroheight / Supernova | окремий портал, зручний для нетехнічних людей, синхронізація з Figma і Storybook | платні, ще одне місце, яке треба тримати в синхроні | великим системам з кількома командами |
| Notion / Confluence | швидко почати, всі вміють редагувати | ручна копія, дрейф гарантований | принципам і процесам, не фактам |
Рекомендація: факти про компоненти - у Storybook поруч з кодом, принципи і процеси - у Notion з посиланнями на Storybook. Чому Storybook дизайнеру варто розуміти самому - у матеріалі Storybook для дизайнерів.
Як не дати документації застаріти?
Генерація розв'язує половину проблеми. Друга половина - перевірка дрейфу: автоматичне порівняння документації з кодом і Figma, яке запускається само, а не тоді, коли хтось згадає.
- Перевірка в кожному PR. Якщо PR змінює
Button.tsx, але не чіпаєButton.mdx, Claude Code (або GitHub Action з ним) порівнює пропси і стани з документацією і пише коментар з розбіжностями. - Токени генеруються, а не копіюються. Таблиця токенів у документації збирається з
tokens.jsonпід час білду. Змінили значення - таблиця оновилась сама. - Документація входить у Definition of Done. Компонент не «готовий», поки в нього нема MDX-сторінки без
TODO: review. - Звірка з Figma раз на спринт. Експорт змінних з Figma порівнюється з
tokens.json, розбіжності йдуть у CHANGELOG. - CHANGELOG пише Claude. З історії комітів між релізами - чернетка змін людською мовою: що додали, що перейменували, що зламає старий код.
Промпт для перевірки дрейфу в PR:
Порівняй змінені в цьому PR компоненти з їхніми .mdx-сторінками.
Знайди: пропси, яких нема в документації; пропси з документації, яких нема в коді;
стани без сторі; токени в документації, яких нема в tokens.json.
Нічого не виправляй. Видай список розбіжностей і чернетку правок для .mdx.Як я збираю таку перевірку наживо на реальному репозиторії, показую на YouTube-каналі UX Hero.
Для кого документація у 2026: для людей чи для AI-агентів?
Для обох, і це новий аргумент на користь документації в репозиторії. Cursor і Claude Code перед написанням інтерфейсу читають AGENTS.md, сторі і MDX-сторінки. Якщо там написано «для деструктивних дій бери Button variant="danger", не червоний текст», агент так і зробить. Якщо документації нема або вона застаріла, агент вигадує власну кнопку з хардкод-кольором.
Тому шар для агентів варто тримати коротким і точним - як це влаштувати, розібрано в статті AGENTS.md для дизайн-системи.
Тут і пролягає різниця, на якій стоїть UX Hero. Згенерувати красиву картинку інтерфейсу вміє будь-яка нейромережа. Довести систему до коду так, щоб її документація жила разом з продуктом і її розуміли і люди, і агенти, вміє дизайнер, який працює з кодом.
Часті питання
Чи може AI сам написати документацію дизайн-системи?
Факти - так: таблиці токенів, пропси, стани, приклади коду і чернетки описів Claude генерує з файлів проєкту за хвилини. Рішення - ні: коли компонент брати, а коли ні, і чому система влаштована саме так, пише дизайнер. AI робить чернетку, людина її затверджує.
Чому документація дизайн-системи постійно застаріває?
Бо вона живе окремою копією від коду і Figma. Компонент змінили в коді, а сторінку в Notion ніхто не оновив. Рішення - генерувати фактичну частину з тих самих файлів, з яких збирається продукт, і перевіряти розбіжності в кожному pull request.
Де краще тримати документацію: Notion, zeroheight чи Storybook?
Для команди, де дизайн доходить до коду, найкраще працює Storybook з MDX-сторінками в тому самому репозиторії: документація оновлюється разом з компонентом. Notion підходить для принципів і процесів, zeroheight - коли систему ведуть кілька команд і потрібен окремий портал.
Чи потрібна документація, якщо компоненти пише AI-агент?
Потрібна ще більше. Cursor і Claude Code читають AGENTS.md, сторі і MDX-сторінки як контекст. Без них агент вигадує власні кольори і другу кнопку, з ними бере ваші токени і компоненти.
Де навчитись вести дизайн-систему з AI українською?
На курсі UX Hero «Дизайн-система з AI» від Dmytro Nikolaienko: аудит, Figma Variables, компоненти зі станами, документація і пайплайн до Storybook на живих файлах.
Почніть з одного компонента: згенеруйте його сторінку з файлів, вичитайте, виправте шаблон. Коли шаблон стабільний, решта бібліотеки - питання одного вечора, а перевірка в PR зробить так, що через пів року документація все ще казатиме правду.