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 ringborder/default, border/input, focus/ring
--radiusбазовий радіус, від нього рахуються іншіradius/base

Головне правило: primitives (ваша палітра) лишаються у вас, а shadcn-змінні посилаються на них як semantic. Не вписуйте HEX напряму в --primary, інакше при ребрендингу правитимете тему руками. Як побудувати шари - у статті Design tokens простими словами, а як Tailwind v4 читає змінні - у матеріалі Tailwind v4 @theme.

Як зробити зі shadcn/ui свою дизайн-систему: покроково

  1. Узгодьте назви у Figma. Офіційного Figma-кита від автора shadcn/ui немає, є community-кити, частина безкоштовні. Беріть той, де змінні названі так само, як CSS-змінні теми, або перейменуйте свій семантичний шар під ці назви. Це найдешевший крок і він економить години далі.
  2. Ініціалізація проєкту. Claude Code запускає npx shadcn@latest init, створює components.json і globals.css. Для дизайнера без терміналу все це робиться промптом у застосунку Claude, без ручних команд.
  3. Тема з ваших токенів. Експортуйте 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 → токен, і список змінних без відповідника.
  1. Додайте першу хвилю компонентів. Button, Input, Select, Checkbox, Dialog, Card, Badge, Toast. Тільки ті, що реально є у ваших макетах, а не весь каталог.
  2. Перепишіть компоненти під свою систему. Тут 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.
  1. Зафіксуйте правила в AGENTS.md. «Нові компоненти тільки через shadcn add, потім адаптувати під docs/specs», «кольори тільки з теми», «не чіпати components/ui без задачі». Без цього наступний промпт «зроби сторінку налаштувань» поверне дефолтні класи. Шаблон - у статті AGENTS.md для дизайн-системи.
  2. Підключіть 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», система вже працює.