Полное руководство по дизайн-системам: пошаговое руководство

2 из 2 серии: полное руководство по дизайн-системам

Инжиниринг | Пошаговое руководство

Как и было обещано в предыдущем посте, в этом посте я намерен показать и подробно описать элементы в этом репозитории.



gstvribs / monorepo-angular-component-library
Это доказательство концепции структуры monorepo для обслуживания компонентов angular и токенов дизайна. Это монорепозиторий… github.com



В структуре проекта мы будем использовать Lerna, Commitzen и Традиционные коммиты. Кроме того, для документации мы будем использовать Storybook и Compodoc, хотя основная цель этого репозитория - обслуживать компоненты для проектов, разработанных на Angular, я покажу альтернативы для создания такой же структуры с другими фреймворками, такими как React.

Для проектов, использующих Android, iOS и другие технологии, некоторые концепции могут быть повторно использованы, например, управление пакетами, теги выпуска и управление исходными версиями, но для управления монорепозиторием, совместного использования зависимостей и создания пакетов требуются некоторые адаптации.

Распространение как монорепо

Это базовая структура для всей системы проектирования, которую вы собираетесь построить, и, чтобы сделать ее доступной для проектов, мы используем структуру, в которой с помощью одного монорепозитория мы создадим пакет, содержащий все строительные блоки, известные как токены доступный проект: цвета, шрифты, типографии и т. д.

Что касается библиотеки пользовательского интерфейса, мы опубликуем множество пакетов, таких как компоненты, модули и службы, как описано на изображении выше.

А для Правил мы будем использовать единое место, которое будет служить единственным источником истины для правил для принципов проектирования, руководств по реализации и руководств по вкладу.

Для правил важнее всего то, чтобы они оставались в одном месте, и чтобы разработчики и дизайнеры использовали один и тот же источник правды при поиске ресурсов проекта. Для этого есть несколько хороших инструментов, и один хороший, который я рекомендую, называется Zeroheight; это позволяет документировать руководство по стилю, токены и принципы в одном месте.

Распространение пакетов и управление ими не так просто, как кажется, и в этом сценарии мы используем monorepo для управления пакетами. Основными преимуществами такого подхода являются:

  • Совместное использование зависимостей между пакетами
  • Подъем
  • Совместное использование конфигураций
  • Уметь распространять независимые пакеты

Этот файл выше - lerna.json, главный файл конфигурации для Lerna. Важные моменты, на которые следует обратить внимание в этом файле:

  • версия: независимые версии каждого пакета
  • allowBranch: позволяет только перечисленным ветвям иметь возможность автоматически помечать версии с помощью двух команд: lerna publishи lerna version
  • changelogPreset: это предустановка обычных коммитов, важно установить это поле так, чтобы команда lerna version использовала правильную версию пакетов на основе используемой вами предустановки. В этом проекте мы используем стандартный журнал изменений Angular, используемый командой Angular. Доступно множество предустановок, которые вы можете проверить здесь.

Обычные коммиты

У нас есть очень точные правила форматирования сообщений git commit. Эта функция используется для достижения двух целей: более удобочитаемые сообщения, чтобы помочь при анализе журнала изменений проекта и создании версий основных | второстепенный | патч после семантического управления версиями

Чтобы мы могли это использовать, мы используем обычные коммиты, следуя стандартному конвенциональному-changelog-angular, который используется основной командой Angular в самых @ angular пакетах для стандартизации сообщений коммитов, определяющих следующую версию. пакета. Если хотите узнать больше - читайте здесь.

<type>(<scope>): <your commit message here>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Таким образом, тип определяет версию пакета. Другими словами, он должен отражать реальные изменения, вносимые в код. Итак, чтобы обновить конкретную версию на основе последних изменений, нам нужно использовать эти типы:

  • основное: ПРЕРЫВАНИЕ ИЗМЕНЕНИЙ
  • второстепенный: подвиг
  • патч: сборка, рутинная работа, ci, исправление, улучшение, производительность, рефакторинг, стиль, тест, документы, откат

Структура для компонентов

Что касается структуры проекта, у нас есть следующие каталоги, за которыми следит Лерна components и tokens. Каждый компонент имеет свой package.json и следует той же стандартной файловой структуре для проекта, а именно:

  • component.html: шаблон компонента
  • component.scss: стили
  • component.ts: логика и привязки компонентов
  • spec.ts: модульные тесты
  • module.ts: модуль с импортом необходимых угловых библиотек и экспортом самого компонента.
  • sandbox.ts: разработка и тестирование компонентов в Angular Playground
  • Stories.ts: документация сборника рассказов
  • README.md: простая уценка, рассказывающая пользователям, как они устанавливают модуль и компонент в какое-либо приложение.

И один index.ts, экспортирующий только два файла, которые нам нужны для создания сборки компонента. Этот файл является точкой входа, которую ng-packagr просматривает для создания пакета.

export * from './lib/button.component';
export * from './lib/button.module';

Структура для токенов

Этот каталог предназначен для размещения переменных, функций и миксинов всех токенов, связанных с вашей системой проектирования; такие вещи, как цвета, типографика, помощники, интервалы, тени и т. д. Это должен быть автоматический процесс, например, есть репозиторий токенов в Figma или Sketch, через API он ищет и преобразует токены в формате словаря стилей и может автоматически генерировать файлы sass, скомпилированные с токенами. Иногда это решение может быть необходимо, но в большинстве случаев это решение излишка в вашем проекте. В этом сценарии это будет больше зависеть от того, насколько токены меняются с течением времени, и от того, что это не должно происходить так часто.

Кроме того, выходные данные этого пакета содержат файлы: bundle-soft.scss и bundle-hard.scss. Эти два параметра похожи, но разница заключается в следующем: жесткая - это реализация, которая изменяет стили непосредственно в элементах HTML, например: h1, h2, h3, h4, pиa; таким образом, soft - это реализация, которая предоставляет классы только с префиксом tokens-h1, tokens-h2 и т. д.…

Автоматические релизы

Используя одну команду lerna publish для публикации пакетов, мы смогли сделать три вещи:

  • Проанализировать историю изменений компонентов и выявить только те пакеты, которые были изменены.
  • Используйте правильную версию на основе используемой предустановки журнала изменений и в соответствии с семантическим управлением версиями
  • Версии тегов Git и создание или обновление текущего журнала изменений пакетов

Шаг за шагом

Итак, давайте внесем небольшие изменения в компонент кнопки, чтобы показать вам, как работает весь процесс.

Изменение будет довольно простым: мы добавляем два новых свойства к компоненту, который называется ariaLabel и ariaPressed.

Перед фиксацией, чтобы протестировать эти новые свойства, мы задокументируем это изменение.

А теперь адаптируем файл песочницы для игровой площадки.

И запустите npm run start:playground, чтобы проверить, работает ли!

Отлично, теперь давайте задокументируем эти новые свойства в файлах историй.

И запустите npm run start:storybook, чтобы проверить, работает ли!

Отлично, теперь давайте сделаем это.

git commit -m "feat(button): add new prop ariaLabel and ariaPressed"

Тип, который мы будем использовать, - это подвиг, потому что мы добавляем что-то новое, что ничего не сломает, если вы продолжите ничего не передавать.

Как правило, на этом этапе вы должны настроить свой CI / CD, но я создал этот сценарий оболочки для представления шагов.

И теперь у нас есть два варианта: протестировать публикацию в локальном npm в verdaccio, запустив npm run publish:local или npm run publish:ci для общедоступного npm. Здесь я опубликую его в реестре npm.

Как мы видели на гифке выше, lerna использовала правильную версию пакета с новыми функциями и создала теги и журнал изменений, вот фиксация.

Последний шаг - создать релиз на Github, где мы можем просто взять контент CHANGELOG.MD, созданный lerna, и использовать его с последним примененным тегом.

Переход на React

Если ваш проект не использует Angular, вы можете увидеть нижеприведенный сценарий возможной миграции на React и его применения к используемой вами структуре, или если вы используете vanilla.

Самые большие изменения в этой структуре, которые также работают и в React, касаются двух вещей: связки и lint. К сожалению, в этой миграции мы потеряли Compodoc и Angular Playground, и на момент написания этого поста мы до сих пор не нашли инструмент, точно сопоставимый с обоими, есть несколько хороших альтернатив, таких как React Styleguidist и Докз .

Таким образом, главное изменение всего проекта - это миграция ng-packagr на webpack. Поскольку React дает нам больше свободы, у нас есть уникальный файл конфигурации для приложений, и мы можем создавать псевдонимы для путей к компонентам на случай, если нам понадобится импортировать их друг в друга.

Также вы можете проверить весь код в репо.



gstvribs / monorepo-react-component-library
Это доказательство концепции структуры монорепозитория, служащей для реагирования компонентов и проектных токенов. Это монорепозиторий… github.com



Мои два цента

  • Для пакетов @angular, @react, @vue и т. Д. Эти зависимости используются как peerDependencies; это наиболее рекомендуемый подход, чтобы ваша упаковка стала легче и более совместимой.

Мне вообще нужно указывать angular / core как зависимость? Если кто-то использует мою библиотеку, у них уже будет существующий проект Angular. Цитата Тодда Палмера о npm peerDependencies

  • Когда вашему компоненту A нужен компонент B, всегда ставьте компонент B как зависимость от компонента A, не импортируйте напрямую, ng-packagr и webpack не поддерживают относительный импорт вне корневой папки компонента, и для этого есть причина. Вы можете найти обходные пути, например использовать псевдонимы, но для вашего «клиента» полезно более четко указать зависимости.

Заключение

Я надеюсь, что это руководство поможет вам создать вашу первую дизайн-систему или поможет с некоторыми идеями о поддержке пакетов. Не стесняйтесь обращаться ко мне в twitter с любыми вопросами и оставлять отзывы, это мне очень помогает!

Благодарим Ивама Луса и Марсело Коста за отзыв!