English for Storybook Developers

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

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

• Історія Один приклад компонента з назвою, відтворений з певним набором властивостей і стану. Компонент зазвичай має кілька історій — одну для кожного значущого варіанту. Слово є як підраховуваним («write a story»), так і використовується як сукупний іменник («update the stories for this button»).

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

• Нет, нет, нет Термін Storybook для реквізитів (або аргументів), переданих компоненту у сюжеті. Аргументами можна керувати інтерактивно у інтерфейсі користувача Storybook, що спрощує дослідження станів компонентів без редагування коду. Приклад: «Я встановив аргумент variant на 'destructive' в статті, щоб рецензенти могли бачити червоний стиль попередження.»

** Типи аргументів ** Метадані, які повідомляють Storybook, як відображати елементи керування для кожного аргументу — який тип елемента, які значення він приймає, і яким має бути вигляд віджета керування. Типи аргументів зазвичай виводяться автоматично з типів TypeScript.

• Приклад: « Я додав argType для size з параметрами ['sm', 'md', 'lg'], тому на панелі керування буде показано спадне меню. » *

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

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

Додаток Додаток, який розширює функціональність Storybook. Name Серед звичайних додатків можна назвати Controls (для інтерактивних аргументів), Actions (для запису подій у журнал), Accessibility (для перевірок a11y) і Viewport (для тестування відповідності). Приклад: «Додаток доступності позначив відсутність aria-label на кнопці піктограми — я виправлю це перед об’єднанням PR.»

Контроль Інтерактивна панель у інтерфейсі Storybook, за допомогою якої ви можете змінювати значення аргументів у реальному часі і переглядати перевідтворення компонента. Засновано на додатку Controls, який вбудовано у Storybook 6 і пізніших версіях.

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

Полотно Головна область перегляду у Storybook, де буде відтворено компонент. Після вибору статті на Полотні буде показано компонент у окремому вигляді, без зв’ язку з навколишнім розкладом програми.

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

Автодок Функція Storybook, яка автоматично створює сторінку документації для компонента з його історій, типів аргументів і коментарів JSDoc. Увімкнено з мітчем autodocs у типовому експорті компонента.

• Приклад: « Ми увімкнули autodocs для всіх компонентів у системі проектування, отже сторінка документації завжди синхронізується з статтями. » *

Звичайні фрази

** В обзорах коду: **

• «Цій історії не вистачає об’єкта args — компонент відтворює з усіма невизначеними пропами. Чи можете ви додати Default історію з розумними за замовчуванням?»
• « Тут наведений декоратор дублюється у кожному файлі історії у цій теці. Пересунути його на .storybook/preview.ts, щоб він застосовувався глобально»
• «ArgTypes для onClick prop повинні використовувати action addon, щоб рецензенти могли бачити клацання подій, що записуються в панелі дій»

В стоячих позах:

• «Я додаю історії для всіх компонентів форми цього спринту, щоб команда дизайнерів могла переглянути стани без необхідності в локальному середовищі розробки»
• «Додаток доступності зараз не працює на трьох компонентах — я працюю над порушеннями, перш ніж ми ввімкнемо перевірку доступності в CI»
• «Autodocs генерує сторінку документації автоматично з наших типів TypeScript, тому нам більше не потрібно підтримувати окремий файл docs.»

** У документації: **

• «Кожна історія експортує названий об’єкт, який зливається з типовим args, визначеним у типовому експорті компонента»
• «Декоратори, визначені в preview.ts, застосовуються до кожної історії в проекті; декоратори, визначені в файлі історії, застосовуються тільки до історій в цьому файлі»
• «Canvas URL стабільний за історією — ви можете поділитись посиланням безпосередньо на певний стан компонента з вашою командою дизайнерів»

Фрази, яких слід уникати

** Використання слова « сторінка компонента » замість « Полотно » ** — у Storybook область, де відтворюється компонент, називається Полотно. Термін « сторінка » є неоднозначним і його можна сплутати зі сторінкою документації Storybook. Використовуйте « Полотно » для перегляду у режимі реального часу і « Сторінка документації » або « autodocs » для перегляду документації.

** Якщо ви кажете « параметри », коли маєте на увазі « аргументи » ** — Storybook має як args (вхідні дані компонентів), так і parameters (налаштування рівня історії, яке керує додатками і поведінкою Storybook). Вони різні. Якщо ви хочете змінити те, що відтворює компонент, ви змінюєте args. Якщо ви хочете змінити поведінку доповнення для цієї історії, ви змінюєте parameters.

** Використання виключно « props » ** — Використання « props » в порядку в контексті React, але в обговореннях Storybook, краще використовувати термін « аргументи », оскільки історії не залежать від фреймворку. У команді, яка використовує React і Vue, сказати «args» завжди однозначно; сказати «props» може збентежити розробників Vue.

Краткий справочник

Term	How to use it
story	”Write a story for every meaningful visual state of the component.”
args	”Set the args in the story to match the most common production usage.”
decorator	”Wrap stories in a decorator to provide the router or theme context.”
addon	”The Accessibility addon runs axe-core checks on every story.”
autodocs	”Enable autodocs with the autodocs tag on the default export.”

Науковий керівник: професор, професор кафедри англійської мови

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

Однією з найпоширеніших перешкод є очікуваний рівень деталізації. « Це працює » недостатньо. Замість того, щоб сказати: « Я завершив реалізацію кнопки », розгляньте щось на зразок: « Я реалізував компонент кнопки з вказаним стилем primary і додав атрибути доступності для навігації за допомогою клавіатури, як це описано у статті « Книга історій ». Зауважте зміну — це більш описове слово, воно демонструє розуміння вимог і активно вирішує потенційні проблеми. Аналогічно, під час написання описів PR уникайте нечітких вказівок на зразок « Виправлено помилку ». Замість цього спробуйте « Виправлено проблему, коли поле вводу неправильно перевіряло введені користувачем дані, що спричинило відсилання незавершених форм. Впроваджено перевірку на стороні клієнта за допомогою [назва бібліотеки JavaScript], щоб забезпечити цілісність даних. » Цей рівень деталізації не лише стосується ретельності; це ознака професійної відповідальності і зменшує неоднозначність для переглядачів.

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

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

storybook add --type story my-component --path stories/my-component

Ця команда показує типовий процес роботи: використання інтерфейсу командної рядки storybook для створення нової історії Storybook для вашого компонента. Фраза тут – «створити нову історію Storybook» – це саме той вид чіткої, дієвої мови, з якою ви регулярно стикаєтеся. Це про передачу того, що ви робите і як ви це робите, таким чином, щоб інші могли легко слідувати.