shadcn/ui - це не бібліотека, яку ставлять залежністю, а набір готових React-компонентів, код яких копіюється прямо у ваш проєкт і стає вашим. Для дизайнера це найкоротший шлях до дизайн-системи в коді: замінюєте його тему своїми токенами з Figma, переписуєте компоненти під свої стани з Claude Code і фіксуєте правила, щоб AI не повертав «дефолтний shadcn». Без цих кроків ви отримуєте не систему, а ще один сайт, схожий на тисячі інших.
Нижче - що таке shadcn/ui простими словами, як його тема мапиться на Figma Variables, покроковий план з промптами і де shadcn/ui не підходить. Так я, Dmytro Nikolaienko, збираю інтерфейси в проєктах UX Hero, і цю логіку ми розбираємо на курсі «Дизайн-система з AI».
Що таке shadcn/ui простими словами?
shadcn/ui - це відкритий код компонентів інтерфейсу на Radix UI (поведінка і доступність) і Tailwind CSS (стилі), який CLI-команда додає у ваш репозиторій як звичайні файли. Команда npx shadcn@latest add button не ставить пакет, а створює components/ui/button.tsx, який можна відкрити і змінити як завгодно.
| Класична UI-бібліотека (MUI, Ant) | shadcn/ui | |
|---|---|---|
| Де живе код | у node_modules, чужий | у вашому репо, ваш |
| Як змінити кнопку | перевизначати стилі й теми бібліотеки | редагувати сам файл кнопки |
| Оновлення | одна команда, але ламає кастомізацію | вибірково, ви вирішуєте, що забрати |
| Доступність | вбудована | вбудована через Radix UI |
| Вигляд «з коробки» | впізнаваний стиль бібліотеки | нейтральний, впізнаваний як «shadcn» |
Саме через модель «код твій» shadcn/ui підходить для дизайн-системи: ви не боретесь з чужою бібліотекою, а редагуєте свої файли. Різницю між системою і набором макетів я розбирав у статті Дизайн-система vs UI-kit.
Чому AI так часто генерує код саме на shadcn/ui?
Бо це один з найпоширеніших стеків у сучасних React-проєктах. Lovable і v0 будують інтерфейси на shadcn/ui за замовчуванням, тож моделі бачили його в тисячах репозиторіїв. Для дизайнера це два наслідки:
- Плюс: Claude Code рідко помиляється в структурі shadcn-компонентів, пропсах і варіантах. Попросили Dialog з формою - отримали робочий Dialog з фокусом і закриттям по Esc.
- Мінус: без своєї теми ваш продукт виглядає як кожен другий AI-прототип: ті самі сірі кнопки, радіус 0.5rem, Inter. Користувач цього не сформулює, але відчує «шаблонність».
Тому задача дизайнера тут не «зробити екран» (це AI вже вміє), а зробити так, щоб кожен згенерований екран говорив мовою вашого бренду. У цьому й різниця між генерацією і дизайн-системою.
Як тема shadcn/ui мапиться на Figma Variables?
Уся тема shadcn/ui - це CSS-змінні в globals.css: окремо для світлої теми в :root і для темної в класі .dark. З Tailwind v4 вони підключаються через @theme inline, а кольори за замовчуванням записані в OKLCH. Ось як вони лягають на семантичний шар у Figma:
| CSS-змінна shadcn/ui | Що це | Семантичний токен у Figma |
|---|---|---|
--background / --foreground | фон сторінки і основний текст | surface/default, text/default |
--primary / --primary-foreground | головна дія і текст на ній | action/primary, text/on-primary |
--muted / --muted-foreground | приглушені фони і вторинний текст | surface/subtle, text/secondary |
--destructive | небезпечні дії й помилки | status/danger |
--border, --input, --ring | обведення, поля, focus ring | border/default, border/input, focus/ring |
--radius | базовий радіус, від нього рахуються інші | radius/base |
Головне правило: primitives (ваша палітра) лишаються у вас, а shadcn-змінні посилаються на них як semantic. Не вписуйте HEX напряму в --primary, інакше при ребрендингу правитимете тему руками. Як побудувати шари - у статті Design tokens простими словами, а як Tailwind v4 читає змінні - у матеріалі Tailwind v4 @theme.
Як зробити зі shadcn/ui свою дизайн-систему: покроково
- Узгодьте назви у Figma. Офіційного Figma-кита від автора shadcn/ui немає, є community-кити, частина безкоштовні. Беріть той, де змінні названі так само, як CSS-змінні теми, або перейменуйте свій семантичний шар під ці назви. Це найдешевший крок і він економить години далі.
- Ініціалізація проєкту. Claude Code запускає
npx shadcn@latest init, створюєcomponents.jsonіglobals.css. Для дизайнера без терміналу все це робиться промптом у застосунку Claude, без ручних команд. - Тема з ваших токенів. Експортуйте Figma Variables у
tokens.jsonі дайте промпт:
Перепиши тему shadcn/ui у globals.css з tokens/tokens.json.
Primitives - окремі CSS-змінні (--color-blue-600 тощо).
Змінні shadcn (--primary, --background, --ring...) мають посилатися
на primitives через var(), без прямих HEX і OKLCH.
Світла тема в :root, темна в .dark, значення з відповідних modes у tokens.json.
Онови --radius і шрифт під наші токени. Нічого іншого не змінюй.
Наприкінці дай таблицю: змінна shadcn → токен, і список змінних без відповідника.
- Додайте першу хвилю компонентів. Button, Input, Select, Checkbox, Dialog, Card, Badge, Toast. Тільки ті, що реально є у ваших макетах, а не весь каталог.
- Перепишіть компоненти під свою систему. Тут shadcn/ui стає вашим. Варіанти кнопки в shadcn задаються через cva (class-variance-authority), тож назви варіантів з Figma переносяться майже один в один:
Онови components/ui/button.tsx під специфікацію docs/specs/button.md.
Варіанти як у Figma: primary, secondary, ghost, danger (прибери outline і link).
Розміри sm, md, lg з нашими висотами 32/40/48.
Додай стан loading зі спінером і aria-busy.
Тільки змінні теми, жодних довільних класів кольорів на кшталт bg-blue-500.
- Зафіксуйте правила в AGENTS.md. «Нові компоненти тільки через shadcn add, потім адаптувати під docs/specs», «кольори тільки з теми», «не чіпати components/ui без задачі». Без цього наступний промпт «зроби сторінку налаштувань» поверне дефолтні класи. Шаблон - у статті AGENTS.md для дизайн-системи.
- Підключіть shadcn MCP. CLI вміє налаштувати MCP-сервер для Claude Code (
shadcn mcp init), тож агент сам шукає і додає компоненти з реєстру замість того, щоб вигадувати їх з нуля. Разом з Figma MCP це дає ланцюг: агент читає фрейм і збирає його з ваших компонентів.
Орієнтовно, з готовими змінними у Figma: тема і ініціалізація - 1 вечір, адаптація одного базового компонента з прийманням - 30-60 хвилин, перша хвиля з 8 компонентів - тиждень у спокійному темпі.
Коли shadcn/ui не підходить?
| Ситуація | Що краще |
|---|---|
| Продукт не на React (Vue, Svelte, нативний iOS) | community-порти для Vue і Svelte або нативні компоненти; для iOS - SwiftUI на тих самих токенах |
| Кілька продуктів мають ділити одні компоненти | shadcn як основа, але зібрана у ваш пакет; про це стаття Бібліотека компонентів з Claude Code |
| Команда хоче «поставив і забув» з автооновленнями | класична бібліотека; shadcn вимагає, щоб хтось відповідав за код |
| Сайт-візитка без складних форм і діалогів | прості HTML/CSS компоненти на токенах, shadcn буде зайвим |
Рекомендація: якщо у вас React-продукт і дизайн-система ще не в коді, shadcn/ui - найшвидший старт. Але тільки разом з власною темою і AGENTS.md, інакше ви економите тиждень зараз і платите впізнаваністю бренду потім.
Як я переношу тему з Figma в shadcn/ui і приймаю компоненти наживо, показую на YouTube-каналі UX Hero.
Чому цим має займатись дизайнер?
Бо в shadcn-проєктах ламається саме дизайн: тема лишається дефолтною, стани «потім», радіуси і відступи пливуть від промпту до промпту. Розробник спокійно відправить у прод дефолтну кнопку, бо вона працює. Дизайнер, який сам доводить тему і компоненти до коду, закриває цей розрив на рівні джерела.
На цьому стоїть UX Hero: картинки і екрани сьогодні генерує будь-хто. Цінним лишається той, хто робить так, щоб згенерований код виглядав і поводився як ваш продукт.
Часті питання
shadcn/ui - це дизайн-система?
Ні, це заготовка для дизайн-системи. shadcn/ui дає доступні React-компоненти на Radix UI і Tailwind CSS з нейтральною темою. Своєю системою він стає, коли ви замінюєте тему своїми токенами, переписуєте компоненти під свої стани і варіанти та фіксуєте правила в AGENTS.md.
Чи є офіційний Figma-кит shadcn/ui?
Офіційного кита від автора shadcn/ui немає, є community-кити, частина з них безкоштовні. Обирайте той, де назви Figma-змінних збігаються з CSS-змінними теми (background, primary, border, ring), тоді перенесення токенів у код займає хвилини.
Чи можна використовувати shadcn/ui без знання React?
Так, якщо компоненти додає і править Claude Code, а ви ставите задачі й приймаєте результат у браузері або Storybook. Базове розуміння пропсів і станів допомагає, але писати React руками для старту не потрібно.
Чому AI-інструменти так часто генерують код саме на shadcn/ui?
Бо це один з найпоширеніших стеків у сучасних React-проєктах: Lovable і v0 будують інтерфейси на ньому за замовчуванням, тож моделі добре його знають. Плюс для дизайнера: Claude Code рідко помиляється в його структурі. Мінус: без своєї теми продукт виглядає як тисячі інших.
Де навчитись робити дизайн-систему в коді українською?
На курсі UX Hero «Дизайн-система з AI» від Dmytro Nikolaienko: аудит, Figma Variables, компоненти зі станами, документація і пайплайн до коду на живих файлах. React, деплой і повний цикл дизайнера, що кодить, веде курс «Design Engineer».
Почніть з теми: ваші токени в globals.css замість дефолтних, одна кнопка під вашу специфікацію і три рядки в AGENTS.md. Коли перший згенерований екран виглядає як ваш продукт, а не як «ще один shadcn», система вже працює.