4B Pen

Appearance

Экспорт ​

CLI экспортирует дизайн в растровые изображения, векторную графику, отдельные документы .fig, JSX, HTML или истории Storybook.

Изображения и .fig ​

sh
openpencil export design.fig                           # PNG по умолчанию
openpencil export design.fig -f jpg -s 2 -q 90        # JPG, масштаб 2×, качество 90
openpencil export design.fig -f webp -s 3             # WEBP, масштаб 3×
openpencil export design.fig -f svg                   # SVG
openpencil export design.fig -f fig --page "Page 1"   # одна страница в отдельном .fig
openpencil export design.fig -f fig --node 1:23        # один объект в отдельном .fig
openpencil export design.fig -f html --css tailwind    # фрагмент HTML с классами Tailwind

Параметры:

  • -f — формат: png, jpg, webp, svg, jsx, html, fig или storybook;
  • -s — масштаб от 1 до 4;
  • -q — качество от 0 до 100, только для JPG и WEBP;
  • -o — путь к выходному файлу;
  • --page — имя страницы;
  • --node — идентификатор объекта.

JSX ​

Чтобы получить JSX с классами Tailwind:

sh
openpencil export design.fig -f tailwind-jsx    # или: -f jsx --style tailwind

Параметр --style openpencil выбирает собственный формат JSX 4B Pen. Подробнее — в разделе Рендерер JSX.

HTML ​

По умолчанию команда создаёт фрагмент HTML со встроенными стилями. Вместо них можно использовать классы Tailwind:

sh
openpencil export design.fig -f html
openpencil export design.fig -f html --css tailwind

Параметр --html standalone создаёт полноценный HTML-документ, который можно открыть в браузере. В него входят стили сброса и обёртка страницы. Этот формат предназначен для передачи дизайна и кода, а не для точного воспроизведения отрисовки до пикселя:

sh
openpencil export design.fig -f html --html standalone --css inline
openpencil export design.fig -f html --html standalone --css tailwind
openpencil export design.fig -f html --html standalone --css tailwind --assets external

При автономном экспорте Tailwind CSS компилируется сразу, поэтому браузерная среда Tailwind не требуется. --assets external сохраняет CSS и извлечённые изображения рядом с HTML. В сочетании с ним --fonts assets находит шрифты текстовых объектов SceneGraph через настроенных поставщиков веб-шрифтов и создаёт локальные файлы @font-face.

Экспорт HTML доступен при работе с файлом.

Экспорт в Storybook ​

Команда создаёт по одному файлу CSF3 .stories.ts для каждого набора компонентов или компонента:

sh
openpencil export design.fig -f storybook                      # истории React в ./design-stories/
openpencil export design.fig -f storybook --framework vue -o src/stories
openpencil export design.fig -f storybook --framework html --page "Components"
openpencil export design.pen -f storybook -o src/stories --watch  # повторный экспорт при каждом сохранении
openpencil export 'src/**/*.pen' -f storybook --beside --watch    # истории рядом с каждым дизайном

Дизайн рядом с историями ​

Храните файл дизайна компонента в папке самого компонента и экспортируйте с --beside: истории каждого документа, изображения дизайна и манифест .openpencil-stories.json попадут в папку этого документа, рядом с кодом компонента. Шаблон stories в .storybook/main.ts, например ../src/**/*.stories.ts, подхватит их без дополнительной настройки.

Можно передать несколько документов или шаблон в кавычках, например 'src/**/*.pen', который 4B Pen раскрывает сам (нужен Node.js 22 или новее). Для нескольких документов необходим --beside или --output; --page работает только с одним документом. Документы экспортируются по очереди; если один не удалось экспортировать, остальные всё равно будут обработаны, а команда завершится с ошибкой. --watch следит за всеми найденными документами; документ, созданный после запуска слежения, потребует повторного запуска.

Каждый вариант набора компонентов становится историей, а его свойства вариантов — элементами управления select, поэтому переключение элемента показывает соответствующий вариант. Отдельные компоненты с именами через косую черту, например Button/Primary и Button/Secondary, собираются в один файл Button с элементом управления Variant. Если в дизайне нет варианта для выбранной комбинации, Storybook выдаст ошибку с именем, а не покажет другой вариант.

Истории отображают компонент как HTML со встроенными стилями, как -f html, поэтому среда выполнения 4B Pen не нужна; --framework (react, vue или html) меняет только обёртку и импорт Meta/StoryObj из @storybook/react-vite, @storybook/vue3-vite или @storybook/html-vite. В тексте используются семейства шрифтов документа, которые Storybook должен загрузить сам. Текстовые, логические свойства и свойства подмены экземпляра пока не экспортируются.

В историях есть записи parameters.design для @storybook/addon-designs:

  • 4B Pen: если документ находится внутри текущей папки, это ссылка openpencil://, которая открывает документ в приложении для компьютера и выделяет вариант или его набор компонентов, когда другой слой носит то же имя, что и вариант. Схема обращается к слоям по имени, поэтому история, у которой имена варианта и компонента повторяются у других слоёв, ссылки не получает.
  • Design: PNG варианта в масштабе 2×, записанный в <Name>.design/ рядом с историей и подключённый через new URL(…, import.meta.url), чтобы Vite включил его в сборку. Скопируйте параметр в историю собственного компонента, чтобы сравнить реализацию с дизайном. --no-design-images пропускает отрисовку; подстановка шрифтов подчиняется --font-policy, как при растровом экспорте.

-o задаёт папку вывода. Манифест .openpencil-stories.json в ней записывает, какой документ (путь относительно папки вывода) и какая страница создали каждую историю и изображение; сохраняйте его в репозитории вместе с историями. Экспорт заменяет файлы, созданные предыдущим экспортом того же документа, включая файлы удалённых или переименованных компонентов; с --page — только файлы этой страницы. Прежде чем что-либо менять, команда откажется перезаписывать любой другой файл: написанную вручную историю, историю другого документа или посторонний образ. Если при экспорте одной страницы имена файлов сместились на истории другой страницы, потребуется полный экспорт. Без манифеста существующие истории считаются чужими, поэтому перед повторным экспортом удалите их. --watch оставляет команду запущенной и повторяет экспорт при каждом сохранении документа, так что горячая перезагрузка Storybook следует за дизайном; если сохранённый файл прочитать не удалось, команда сообщает об этом и продолжает следить. Отсутствующая --page или подстановка при --font-policy strict по-прежнему завершают команду.

Миниатюра ​

sh
openpencil export design.fig --thumbnail --width 1920 --height 1080

Экспорт из запущенного приложения ​

Не указывайте файл, чтобы экспортировать текущий документ из приложения:

sh
openpencil export -f png                       # выделение в активном документе
openpencil export --page "Components" -f png   # все слои страницы
openpencil export --node 1:23 -f png           # один слой на любой странице

--page принимает имя страницы, а --page-id — ID страницы из openpencil documents list; любой из параметров экспортирует страницу, не переключая на неё приложение. Добавьте --document-id, чтобы экспортировать из документа, который не является активным.

В режиме запущенного приложения поддерживаются PNG, JPG, WEBP, SVG и PDF. Для PowerPoint, JSX, HTML, Storybook и .fig нужно указать файл. Экспорт миниатюр в режиме файла пока не поддерживается.

Released under the MIT License.