После market’ с спроса на минималистичный и последовательной интерфейсов, и рост модульной веб-разработки, с каждого проекта мы предпринимаем мы платим все больше и больше внимания к документации и эффективность дизайнер-инженер технологического процесса.Кроме того, поскольку процесс документирования часто слабым местом современных веб-команд, we’ повторно постоянно ищем правильные инструменты, чтобы помочь нам .

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

I’ ве расположены инструменты по функциям, выделив только самые мощные из них стоит знать.Вы можете найти больше инструментов, плюс видео, статьи и другие материалы о руководств по стилю на styleguide.io ¹ .

Прежде чем мы начнем, если вы еще не знакомы с гидами стиль жизни, я предлагаю смотреть на эти ресурсы, чтобы получить хорошую подготовку в теме:

• “ Создание Стиль Guides ² ” Сьюзен Robertson
• “ Фронтальный Стиль Guides ³ ” Анна Debenham
• “ Гид по стилю Driven Development ⁴ ” Нико Hagenburger

В двух словах, живущие стиль руководства предназначены для оказания помощи в создании хорошо организованной документации Фронтальный базы кода.По “живой” мы имеем в виду документация находится в постоянном синхронизации с фактическим кодом .

CSS Документация Tools

Первые игроки в области являются CSS документация разбор tools.Идея в том числе описания компонентов в исходном коде стиле впервые приехал с веб-дизайнеров.Сочетание творческого подхода к дизайну стиль руководства с практикой веб реализации привело к развитию KSS ⁵ .

Как JSDoc ⁶ в КСС, компоненты CSS, описаны прямо в исходном коде в виде комментариев .

// A button suitable for giving a star to someone.
//
// :hover             - Subtle hover highlight.
// .star-given        - A highlight indicating.
// .star-given:hover  - Subtle hover highlight.
// .disabled          - Dims the button.
//
// Styleguide 2.1.3.
a.button.star{
  ...
  &.star-given{
    ...
  }
  &.disabled{
    ...
  }
}

KSS позволяет определить компоненты, гид по стилю номера раздела и описать свои различные состояния.Эта информация затем анализируется, создавая либо один документ или набор статических HTML-файлов с оказанные примеров и фрагментов кода .

⁷

В других инструментов CSS документация разбора, это также можно определить HTML разметку в комментариях, в то время как KSS анализирует только фактические селекторы CSS и генерирует простой разметки автоматически .

В настоящее время KSS только решение документации, а также инструмент разбора не обновляется .

Альтернативы KSS

С оригинальной KSS, многие подобные инструменты были освобождены, чтобы сделать точно то же самое.Один из наиболее успешным является SC5 Гид по стилю Generator ^{44 9} , который основан на КСС.В дополнение к инкапсулируется (с помощью Shadow DOM оказанных) компонентов превью, инструмент также позволяет редактировать Sass или менее стилей в браузере.Это также можно определить Angular.js директивы или веб-компоненты, как разметки, например, в CSS комментарии, которые затем будут преобразованы в полностью оперативной составляющей .

К сожалению, большинство инструментов CSS документация скопировать один another’ функциональности с, не вводя новых возможностей (изготовление описания каждый несколько избыточным), но имеющиеся них включают в себя: StyleDocco ¹⁰ ; Колей Styleguide ¹¹ (на стороне клиента только); Hologram ¹² ;и Styledown ¹³ .

Одним из инструментов, однако, более четкими. DSS ^{45 14} является только автономный CSS документация анализатор, который производит JSON для последующего шаблонов.DSS базируется на Node.js с поддержкой всех современных препроцессоров.По сравнению с КСС, можно интегрировать DSS в любой другой инструмент или среды, как оригинал Автор также делали с DSS Грунт plugin ¹⁵ .

Руководство по стилю Platforms

В то время как они просты в реализации, CSS документация анализаторы весьма ограничены.Если попробовать описать сложные компоненты в CSS, вы будете в конечном итоге с раздутой и трудно управлять стили, содержащие много скопировать и вставить HTML фрагменты всему коде .

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

Если у вас есть серьезные планы на поддержание собственной библиотеки компонентов пользовательского интерфейса, это лучше выбрать альтернативный группу инструментов, которые я называю Руководство по стилю platforms.Будь they’ Re статический генераторы сайт или динамические среды, гид по стилю платформы обеспечивают альтернативные и масштабируемые решения для сопоставления документации .

Статический Гид по стилю Generators

Наиболее простой пример из руководства по стилю генератора статического переднего плана План Primer ¹⁶ .Это просто соединяет список HTML-файлов в один документ, что вы можете улучшить с краткими текстовыми описаниями и примерами кода .

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

План Lab

План Lab ¹⁷ также объединяет набор шаблонов в статическом гид по стилю сайта.Но на вершине, что он также предоставляет множество полезных функций, таких как навигация, поддержка аннотаций и смарт-шаблонов .

Каждый инструмент должен иметь рабочий процесс и шаблон Lab делает это лучше, сочетая структуру с атомного design ¹⁸ захода на посадку.Это идеальное сочетание для легкого создания прототипов и прохождения HTML-разметку для клиентов или фоновых разработчиков.Тем не менее, вы можете обнаружить, что его строгое позиция по технологиям и именования файлов может помешать существующей кодовой базы и индивидуальных требований .

¹⁹

План Lab устанавливает _patterns каталог с подпапки для каждого компонента, после именования.Каждая папка содержит набор шаблонов logicless усы HTML-разметки .

²¹

Данные для шаблонов определяется на глобальном уровне, или может быть установлена ​​локально рядом с самим разметки:

pages/article.mustache
pages/article.json

Все that’ S Влево, чтобы связать стили проекта в общий шаблон страницы и запустить шаблон Лаборатории строитель.Просмотр результирующего демонстрационную страницу генерируемого шаблона библиотеки .

Другое Generators__31 статический сайт |

Есть несколько инструментов, после аналогичных. Fabricator ²³ сопоставляет HTML и Markdown файлы, обеспечивая большую гибкость в документации компонента структурирования .

²⁴

План Lab позволяет определить данные шаблона рядом с источниками усы;с Fabricator можно определить Markdown файлы с текстовыми описаниями рядом с источником HTML.Оформление документации осуществляется с помощью Глоток сборки задачу, которая также включает в себя живую перезагрузки для упрощения разработки.Вот пример output ²⁶ порождается Fabricator .

LivingStyleGuide Gem

Еще один инструмент стоит упомянуть LivingStyleGuide Gem ²⁷ на основе Sass и Markdown .

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

@haml
@full-width
***.concept-page***
  ***.concept-page--container***
    %h1***.concept-page--title*** Concept
    ***.concept-page--section***

Вот список демо components ²⁸ использовали в качестве вклада в LivingStyleGuide Gem и в результате одностраничный doc ²⁹ .

Поскольку, как следует весьма самоуверенного набор технологий, большинство выгоды будут получены только с помощью экосистему Руби .

Руководство динамичный стиль Platforms

Чтобы получить еще большую гибкость и более богатые наборы функций, которые можно выбрать динамичный стиль руководство platforms.Отличие от инструментов, упомянутых до сих пор является то, что вместо того, статические веб-сайты, они обеспечивают полноценные веб-приложения .

В настоящее время есть только два хороших примеров направляющих платформах динамичный стиль: Rizzo ^{48 30} ;и SourceJS ^{49 33 31} .

По сравнению с инструментами CSS-ориентированных, гид по стилю платформы более инженер-приводом, охватывающий всестороннего развития и интеграционных процессов, а не только те аспекты HTML разметки и веб-дизайн .

Rizzo

Риццо небольшое приложение, Руби, которая тянет компонентов пользовательского интерфейса активы с помощью специального API, который обеспечивает мастер (основной продукт) приложения.Вместо того чтобы копировать шаблоны и разметка в направляющую хранилище стиле, компонентного тянут там автоматически.В настоящее время лучший способ развивать поистине living стиль руководства, что постоянно находятся в синхронизации с реальным коде, тем самым обеспечивая большую гибкость, чем CSS документации анализаторов .

К сожалению, Риццо очень упрямый и не подходит для легкого повторного использования в других приложениях.Однако, я определенно предлагаю вам узнать больше о идеи, лежащие в it ³² на инженерно блоге Lonely Planet .

SourceJS

По сравнению с Риццо, SourceJS ^{49 33 31} является масштабируемым решением с открытым исходным кодом.Динамичная среда приложение позволяет настроит� …

Если вы хотите прочитать полностью статью, посетите сайт наших спонсоров