English Vocabulary for Storybook Developers

Storybook став промисловим стандартом для розробки і документування компонентів інтерфейсу користувача в ізоляції. Якщо ви працюєте з Storybook і співпрацюєте з дизайнерами, менеджерами продуктів або інженерами англійською мовою, вам потрібна лексика для опису історій, ефективного документування компонентів і участі у обговоренні систем проектування.

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

• Історія Історія у Storybook — це один, названий приклад компонента у певному стані. Кожна історія відтворює компонент з певним набором реквізитів і представляє один випадок використання або варіант.

• Приклад: « Я написав три історії для компонента Button: первинний, вторинний і вимкнений стани. » *

Контроль Керування — це інтерактивна панель у інтерфейсі Storybook, яка надає змогу користувачам динамічно змінювати властивості компонента без редагування коду. Вони дозволяють легко досліджувати поведінку компонента і крайові випадки.

• Приклад: « Ви можете скористатися панеллю керування, щоб перемкнути світлий і темний режими і побачити, як реагує компонент. » *

Декоратор Декоратор у Storybook — це компонент оболонки, який додає контекст або стиль до історії. За допомогою звичайних декораторів можна створювати надання тем, контекст маршрутизатора або обгортки макетів.

• Приклад: « Ми додали декоратор ThemeProvider до всіх наших статей, щоб вони завжди відображалися з правильними символами дизайну. » *

• Нет, нет, нет Аргументи (скорочено від аргументи) — це параметри, які передаються компоненту у сюжеті. У форматі Component Story Format (CSF) аргументи визначаються на рівні статті і можуть бути перезаписані за допомогою елементів керування.

• Приклад: « Типовими аргументами для цієї статті є « Надіслати » і « Основний ». » *

Система дизайну Система дизайну є збіркою компонентів інтерфейсу користувача, які можна використовувати повторно, токенів дизайну, рекомендацій і документації, які команди використовують для створення послідовних інтерфейсів користувача. Storybook зазвичай використовується як жива документація для системи дизайну.

• Приклад: « Наш екземпляр Storybook служить єдиним джерелом правди для нашої системи проектування — кожен компонент документується там з рекомендаціями щодо використання і прикладами. »*

Поширені сценарії, де використовується ця мова

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

** Під час написання документації компонента: ** У документації щодо компонентів у Storybook міститься опис призначення компонента, пояснення, коли його слід використовувати, а також розбивка його властивостей. « Компонент підказки слід використовувати для короткого пояснювального тексту, який доповнює елемент інтерфейсу користувача. Не використовуйте його для критичної інформації, яку користувачі повинні бачити»

** У перегляді запиту на звантаження: ** “Я бачу, що ви додали нову історію для стану помилки — гарно. Чи могли б ви також додати історію на випадок, якщо повідомлення про помилку буде дуже довгим? Я хочу переконатися, що макет грациозно обробляє переповнення тексту»

** При введенні дизайнерів: ** «Наша книга історій доступна на design.example.com. Ви можете переглядати всі наші компоненти, бачити їх різні стани і використовувати панель керування для експериментів з різними значеннями властивостей. Якщо компоненту не вистачає стану, який вам потрібен, підніміть його з командою фронтенду»

Корисні фрази для обговорення книг

• «Дай мені перевірити Storybook, щоб побачити, які варіанти ми вже маємо для цього компонента»
• «Я писав історії для щасливого шляху, стану помилки і порожнього стану.»
• «Панель керування дозволяє змінювати позначку і колір без торкання коду.»
• «Ми використовуємо Chromatic для лову візуальних регресій — він порівнює історії з базовою лінією на кожному запиті на потягування»
• «Компонент задокументований в Storybook з рекомендаціями щодо використання і таблицею реквізитів»
• «Ми використовуємо декоратори, щоб забезпечити тематичний контекст, який очікують всі наші компоненти»
• «Ця історія позначена як застаріла, тому що ми замінюємо цей компонент в наступному випуску системи дизайну»
• Аргументи для цієї історії можуть бути використані як початкові типові значення для контролю
• «Наша книга історій є джерелом правди для системи дизайну — завжди перевіряйте там перед тим, як будувати новий компонент»
• Чи можете ви додати історію, яка демонструє, як цей компонент виглядає в розкладці справа наліво?

Запис документації компонента у Storybook

Сторінка docs в Storybook автоматично генерує документацію з коментарів JSDoc і типів реквізитів. Написання хороших коментарів до документації є не менш важливим навиком англійського письма, ніж технічний.

Хороший опис компонента відповідає на запитання: для чого потрібен цей компонент, коли його слід використовувати, і чи є випадки, коли його не слід використовувати? « Компонент Alert показує користувачеві видне повідомлення. Використовуйте його для важливих відомостей про стан, попереджень або помилок. Не використовуйте його для загального вмісту сторінки або декоративних цілей»

Для описів атрибутів, будьте точними щодо типу і ефекту: « Встановлює візуальний стиль попередження. Використовуйте success для позитивних результатів, warning для обережності, і error для невдач»

Практичні рекомендації

Відкрийте Storybook для будь- якої системи дизайну з відкритим кодом — Material UI, Chakra UI або UK Government Design System — всі ці системи мають публічні Storybooks. Виберіть один з компонентів і уважно прочитайте документацію щодо нього. Потім напишіть опис компонента обсягом 150 слів вашими власними англійськими словами, у якому описайте його призначення, коли його слід використовувати і які функції виконують його найважливіші компоненти. Порівняйте ваш опис з оригіналом, щоб побачити, що ви пропустили або що ви могли б висловити чіткіше.

Розрізняють: мовні стереотипи — стереотипи, що стосуються мовлення людей, які не говорять рідною мовою

Словник, представлений в цій статті - зосереджений на термінології, пов’язаній з Storybook, розробкою компонентів інтерфейсу користувача і спільними потоками роботи - може відчуватися особливо щільним для розробників, чия основна мова не є англійською. Це не просто про те, щоб знати * що * термін означає; це про розуміння нюансів, як ці терміни використовуються в професійному контексті, часто завантажені неявними очікуваннями і встановленими конвенціями. Простого перекладу рідко буває достатньо. Розгляньте, наприклад, різницю між « вада » і « проблема ». Хоча обидва описують проблеми, « вада » зазвичай означає дефект у самому коді, тоді як « проблема » може охоплювати ширші проблеми, такі як користувацька здатність, невідповідності у дизайні або навіть прогалини в документації — речі, які можуть не бути безпосередньо пов’ язані з функціональністю основного коду. Аналогічно, повторювані фрази, такі як «розв’язати», «адреса» або «виправити», можуть відчувати себе вимогливими; вони не завжди передбачають просте рішення, а скоріше зобов’язання зрозуміти і повністю зменшити проблему.

Поширена перешкода виникає при інтерпретації зворотнього зв’язку під час перегляду коду. Отримання коментаря на зразок « Цему компоненту потрібні додаткові параметри » не є просто запитом на додаткові параметри. Це запит на пояснення, чому ці реквізити потрібні, яка їхня призначення, і як вони повинні використовуватися для поліпшення функціональності або гнучкості компонента. Розробник може інстинктивно перекласти «пропорції» як «властивості», але не в змозі зрозуміти контекст перегляду - загальні цілі дизайну, потенційні випадки використання - може призвести до неправильного тлумачення і відчуття несправедливої критики. Аналогічно, при написанні описів PR, метою є ясність і детально. Неясні твердження, такі як «Виявлено помилку», рідко достатньо; надання конкретних відомостей про проблему, реалізоване рішення і будь-які пов’язані зміни зміцнюють процес перегляду і демонструють розуміння.

Іншою областю, де часто трапляються нерозуміння, є термінологія робочого потоку. Такі фрази, як « гарячий латок », « технічний борг » або « переробка » мають значну вагу у командах розробників. « Гарячий латок » — це не просто швидкий латок; це означає термінову відповідь на критичну проблему виробництва, яка часто вимагає ретельного розгляду потенційних побічних ефектів і ретельного тестування. « Технічний борг » рідко пов’ язано з простою заборгованістю з грошей — це накопичені наслідки приоритизації зручності над довгостроковою підтримкою. Зрозуміти цей термін вимагає визнання компромісів, пов’язаних з прийняттям рішення про проектування або реалізацію, які можуть бути доцільними в короткостроковій перспективі, але можуть створити проблеми пізніше.

І, нарешті, не вагайтеся попросити про пояснення. Краще набагато визнати плутанину, ніж робити висновки на основі потенційно помилкового розуміння. Більшість досвідчених розробників з радістю терпляче пояснюють свої аргументи і надають контекст. Просте запитання на зразок: « Чи можете ви розібратися, що ви маєте на увазі під « поліпшенням доступності цього компонента? » демонструє ініціативу і прихильність до навчання, сприяє більш спільному середовищу.

# Example: Running Storybook's snapshot command (illustrating CLI usage)
storybook snapshots add --title "My Awesome Component"