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

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

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

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

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

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

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

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

Подобный JSDoc __59 | | 6__8 в КСС, компоненты 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{
    ...
  }
}

⁷

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

В настоящее время КСС только решение документации и инструмент разбора не обновляется.Хотя it’ сек реализации как КСС-node __23 | 9 еще совершенствуется с полями пользовательскую документацию и лучшей поддержки шаблонов .

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

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

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

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

Гид по стилю Platforms

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

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

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

Руководство Статический Стиль Generators

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

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

Шаблон Lab

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

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

²¹

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

²³

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

pages/article.mustache
pages/article.json

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

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

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

²⁶

Шаблон Лаборатория позволяет определить данные шаблоны рядом с источниками усы;с 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 __22 | 30 используется в качестве вклада в LivingStyleGuide драгоценных камней и в результате одной страницы doc __28 | 31 .

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

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

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

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

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

Rizzo

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

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

SourceJS

По сравнению с Риццо, SourceJS __12 | 51
Если вы хотите прочитать полностью статью, посетите сайт наших спонсоров