Англійська для розробників shadcn/ui

shadcn/ui змінив те, як багато команд думають про бібліотеки компонентів, пропонуючи компоненти копіювання-вставлення, побудовані на Radix і Tailwind, а не встановлений пакунок. Якщо ви працюєте з shadcn/ui у міжнародній команді, вам буде потрібна чітка англійська мова для обговорення права власності на компоненти, тем і налаштування. Цей посібник містить основні слова для розробників shadcn/ui.

Ключовий словник

** Модель копіювання і вставлення компонентів ** — підхід, за якого початковий код компонента додається безпосередньо до вашого проекту, а не встановлюється як залежність з версіями. “За допомогою моделі копіювання-вставлення компонента, ми є власниками коду компонента Button — немає версії бібліотеки, яку слід блокувати під час оновлення.”

** Реєстр ** — збірник визначень компонентів, з якого shadcn CLI може отримати і додати до вашого проекту. “Ми розміщуємо внутрішній реєстр, тому нетипові компоненти нашої команди розробників можна додавати за допомогою тієї ж команди CLI, що й офіційні компоненти.”

** Вариант ** — заздалегідь визначений візуальний або поведінковий стиль компонента, як правило, керується за допомогою програми, на зразок class-variance-authority. “Компонент Button має варіанти default, destructive і outline, кожен з яких відповідає іншому набору класів Tailwind.”

** Значки тем ** — нетипові властивості CSS (змінні), які визначають кольори, радіуси і інтервали системи дизайну, що надає змогу змінювати загальний стиль без зміни коду компонентів. “Ми перезаписуємо --primary і --radius символи в нашому CSS, щоб перефарбувати кожен компонент для нашого продукту з білою етикеткою.”

** Композитивність ** — принцип, за яким компоненти побудовано з менших, не стилізованих примітивів (часто Radix), які можна вільно рекомбінувати і налаштовувати.

• “Оскільки компонент Dialog можна компонувати, ми могли б додати нетиповий нижній колонтитул без розбігу всього компонента.” *

** Slot / asChild ** — шаблон, за допомогою якого компонент можна відтворити як інший підлеглий елемент, зберігаючи його поведінку. Зазвичай, цей шаблон використовується для відтворення кнопки як посилання. “Ми використовували asChild, щоб зробити компонент Button відображати як Next.js Link, тому він отримує стиль кнопки, але поводиться як клієнтська навігація.”

** CLI (компонентний встановлювач) ** — інструмент командного рядка, який використовується для додавання компонентів shadcn/ui та їх залежностей до дерева коду проекту. “Запуск команди CLI add dialog скинув джерело компонента Dialog безпосередньо в нашу теку components/ui.”

** Власність ** — концепція, згідно з якою після додавання компонента до вашої бази коду, ваша команда відповідає за підтримку і оновлення цього компонента, а не зовнішній супровід пакунків. “Оскільки ми є власниками коду компонента, оновлення його для виправлення проблеми з доступністю не вимагало очікування на випуск початкового коду.”

Розглядається питання про настройку та тематику

• «Ми не розрізали компонент Button — ми просто додали новий варіант для вторинного стилю заклику до дії нашого бренду»
• «Зміна нашої теми зі світлого на темний режим є лише питанням обміну значеннями змінних CSS, не торкаючись логіки компонентів»
• “Оскільки ми володіємо кодом, ми вилучили залежність, яку зазвичай включає компонент, який нам не потрібен.”

Розмова про компроміси

• «Компроміс з копіювання-вставлення компонентів полягає в тому, що ми не отримуємо автоматичних виправлень помилок — ми повинні відстежувати оновлення вручну»
• «Власність на компоненти дала нам повний контроль над виконанням наших вимог щодо доступності без очікування на зовнішнього супроводжувача»
• «Ми зберігаємо журнал змін будь-якого компонента, який ми модифікували з оригіналу, тому майбутні співробітники знають, що відхилилося і чому»

Професійні поради

1. ** Поясніть компроміс щодо власника чітко у документації щодо впровадження. ** Нові розробники, які звикли до встановлених npm бібліотек, часто вважають, що компоненти автоматично оновлюватимуться — вони цього не роблять.
2. Задокументуйте будь-які зміни до початкового коду компонента. Це запобігає плутанини при порівнянні вашої бази коду з публічною документацією shadcn/ui.
3. ** Використовувати символи тем замість закодованих значень під час налаштування. ** Це дозволяє зберегти підтримку зміни бренду або темного режиму централізованою і легкою для розуміння.

Практичні вправи

1. Поясніть новому співробітнику команди 3- 4 реченнями, яким чином модель копіювання і вставки компонентів відрізняється від встановлення бібліотеки компонентів за допомогою npm.
2. Напишіть коротке пояснення (4- 5 речень), чому ваша команда вирішила додати нетиповий варіант замість того, щоб повністю розрізати компонент.
3. Описати простим англійським мовою ситуацію, у якій володіння кодом компонента дозволяє вам виправити ваду швидше, ніж чекати випуску початкового коду.

На практиці: Навігація нюансів в колективному середовищі

Ядро того, щоб стати досвідченим розробником, не тільки в тому, щоб знати, як писати код; це ефективне спілкування в команді. Для розробників, які використовують такі фреймворки, як shadcn/ui, особливо ті, що працюють з власниками компонентів, варіантами і темами, точна мова є абсолютно важливою. Часто нерозуміння виникають не з технічних труднощів, а з тонких відмінностей у фразуваннях, які можуть звести нанівець обговорення або призвести до розчарованих переглядів. Розглянемо звичайний сценарій: коментар перегляду коду. Уявіть, що ви надіслали PR, що вводить новий варіант кнопки — « небезпека » — для компонента форми. Рецензент може залишити коментар на зразок: « Це добре, але чи можемо ми * перекодувати * це, щоб використовувати символ theme-color замість жорсткого кодування червоного кольору? » Слово « перекодувати » тут не просто пропонує невелику зміну; воно передбачає глибшу зміну — можливо, реструктуризацію пов’ язаного коду і оновлення документації. Він просить вас узгодити вашу реалізацію з більш широкою стратегією тематики, підкреслюючи область, де послідовність цінується. Аналогічно, розмови Slack про володіння компонентами можуть швидко стати складними, якщо термінологія неясна. Сказати «Я власник цього» не повністю передає відповідальність; краще сказати щось на зразок: «Я відповідальний за підтримку і розширення цього варіанту кнопки в рамках існуючих конвенцій бібліотеки інтерфейсу користувача»

Інша часто зустрічається область плутанини виникає при обговоренні описів PR. Написання переконливого опису - це більше, ніж просто опис того, що ви змінили - це про встановлення очікувань для рецензентів. Замість простого зауваження «Додано варіант кнопки «небезпека», кращим підходом буде: «Ця PR вводить новий варіант кнопки «небезпека» до компонента форми, використовуючи знак theme-color для послідовного стилю в нашій програмі. Це відповідає нашій поточній стратегії створення тем і зменшує потенційні майбутні невідповідності. Варіант було ретельно перевірено і він відповідає встановленим правилам щодо власника компонента. » Цей рівень деталізації показує розуміння більш широкого контексту і заохочує переглядачів зосередитись на * впливі * ваших змін, а не лише на поверхневих модифікаціях. Крім того, активне використання фраз типу «Це адресує…» або «Як частина цієї зміни…» допомагає встановити чіткий зв’язок між метою PR і загальними цілями проекту.

Нарешті, пам’ятайте, що активно слухати і пояснювати завжди краще, ніж припускати, що ви розумієте. Якщо рецензент використовує жаргон, який ви не розумієте, ввічливо попросіть пояснення: « Чи могли б ви розібратися, що ви маєте на увазі під « сприянням послідовності » у цьому контексті? » Не бійтеся визнати, коли вам потрібна додаткова інформація — це демонструє смиренність і бажання вчитися. Сильна комунікація сприяє співпраці середовища, де кожен відчуває себе комфортно, ефективно вносячи свій внесок.

Ось короткий приклад використання tailwindcss для застосування кольору теми:

npx tailwindcss init --safe-mode

За допомогою цієї команди можна ініціалізувати файл tailwind.config.js, за допомогою якого ви зможете визначити кольори та інструменти теми у послідовному порядку. Після цього ви зможете використовувати ці визначені кольори у ваших компонентах за допомогою класу theme-color.