tezis.components

Назначение репозитория / библиотеки

Если просто

Нужна сетка, кнопки, выпадающие меню, табы, аккордеон, слайдеры, модальное окно, но не нужен громоздкий Bootstrap?

Инклуд компонента в любом файле pug, подключение стилей этого компонента, замена кода цвета в переменных sass - и ваш блок готов.

Если подробнее

Переиспользование, универсальность

В работе верстальщика рано или поздно встаёт вопрос переиспользования стилей / сеток / JS - решений.

Выпадающие списки, табы, меню, слайдеры - стандартные элементы, которые можно написать сотнями разных способов, учитывая или не учитывая множество переменных, таких как доступность и пригодность к повторному использованию, лаконичность кода. Вместе с normalize.css и отменой браузерных стилей, мы часто переписываем одно и то же с нуля, либо используем решения других разработчиков, берём из codepen и других хороших ресурсов. Но вопрос более локальной стандартизации наверняка волнует большое количество разработчиков.

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

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

Доступность

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

Например, на данный момент вместо старых свойства отступов и позиционирования используются логические свойства, которые часто можно увидеть в браузере до сброса стилей. Например, вместо margin-top: $ind можно увидеть margin-block-start: $ind. А вместо right: 50% - inset-inline-end. На первый взгляд это сложнее, но эти логические свойства перекликаются c flex и grid layout, отчего учатся очень быстро. Также стоит использовать в text-align вместо старых свойств start и end. Не все логические свойства учитываются в силу того, что пока они не везде работают и не всегда делают смысл. Например, max-inline-(start, end) не работает с медиа запросами. А свойства из разряда border-inline-start-block-end-radius больно нелепо выглядят в верстке, хоть и нечасто встречаются. Поэтому в стандартных стилях используется классический border-(top, bottom, left, right).

Если хотите более детально почитать о логических свойствах, вот неплохая статья.

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

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

Демо

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

Переменные SCSS
Сетка:

SVG-спрайты

Компоненты

Подключение компонентов
Вендорские стили и скрипты:
Список компонентов

README gulp-pug-starter с основами работы сборщика

Особенности
Установка
Файловая структура
Команды
Рекомендации по использованию
Компоненты
Страницы проекта
Шрифты
Изображения
SVG-спрайты
Сторонние библиотеки
Нужен SCSS без Pug?
Нравится проект gulp-pug-starter?
Контакты создателя gulp-pug-starter

Демо

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

Скачайте архив.

Установите глобально:

Yarn: npm i -g yarn
Gulp: npm i -g gulp
Bem Tools: npm i -g bem-tools-core

Откройте папку, где распаковали файлы архива в редакторе кода, на котором работаете и введите:

yarn set version berry, затем yarn для установки всех зависимостей.

После этого процесса запустите локальный сервер с помощью команды yarn run dev и пустой сайт откроется в Вашем браузере по умолчанию.

Сейчас на сайте лишь шапка и подвал.

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

Верстка

Затем пройдите внутрь по пути: ./src/views и откройте файл index.pug.

Найдите строчку include ../blocks/modules/main/main и ниже вставьте

include ../blocks/modules/demo/demo

CSS

Чтобы подключить стили demo-блоков, откройте: ./src/blocks/components/_components.scss и под комментарием // ! Other вставьте данные строки:

@import 'tabs/tabs';
@import 'gallery/gallery';
@import 'flex-gallery/flex-gallery';
@import 'slider/slider';
@import 'accordion/accordion';
@import 'show-more/show-more';
@import 'tabs-tags/tabs-tags';
@import 'breadcrumbs/breadcrumbs';
@import 'circle/circle';
@import 'container-beyond/container-beyond';
@import 'dropdown/dropdown';

JS

Чтобы подключить скрипты demo-блоков, откройте: ./src/js/import/components.js и под комментарием // ! Other вставьте данные строки:

import "%components%/tabs/tabs";
import "%components%/gallery/gallery";
import "%components%/flex-gallery/flex-gallery";
import "%components%/slider/slider";
import "%components%/accordion/accordion";
import "%components%/show-more/show-more";
import "%components%/tabs-tags/tabs-tags";
import "%components%/circle/circle";
import "%components%/dropdown/dropdown";

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

Переменные SCSS

Все цвета и отступы определяются с помощью переменных в ./src/styles/helpers/_variables.scss.

Все значения в верстке заданы переменными, так что настройка проекта начинается с них.

$container - переменная для ширины контейнера контентной части сайта.
$layout-margin - переменная дли отступов контейнера layout контентной части сайта.
$layout-margin-mob - переменная дли отступов мобильной версии контейнера layout контентной части сайта.
$base-color - цвет, используемый в шрифтах и бордерах, а также псевдоэлементов (если в макете цвет шрифта и псевдоэлементов совпадает)
$accent-color - цвет кнопок и ссылок (подчеркивания) и псевдоэлементов, если цвет псевдоэлементов не совпадает с base-color. Также может быть фоновым цветом, если фоновый цвет не отличается от него.
$hover-color - цвет состояния, цвет при наведении
$active-color - цвет состояния, цвет в активном состоянии
$disabled - цвет состояния, цвет элемента в отключенном состоянии, иногда цвет пассивного бордера, можно использовать в бордерах, неакцентное состояние
$bg-color - фоновый цвет
$contrast-color - цвет контраста. Чаще всего белый цвет. Пример использования: белый цвет шрифта при наведении на кнопку, когда для читабельности темный цвет шрифта сменяется на светлый.
$border - настройка бордера, в качестве цвета используется переменная disabled
$brr - основной border-radius. brrmin и brrmax - минимальное (меньшее) и максимальное (большее) значение
$ind - сокр. от indentation, отступ. Универсальное и наиболее часто встречающееся значение отступа. Введено вместо большого количества переменных и миксинов по margin и padding. Коротко и удобно. Так же, как и border-radius, присутствуют минимальное и максимальное значение $indmin $indmax.
$gap а также $gapmin и $gapmax - по сути аналогичны $ind. Но нужны там, где в проекте отступы gap отличаются от отступов между элементами и блоками. В данном случае закомментированы.
$transition - стандартные длительность и тип анимации.

Дополнительные переменные цвета

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

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

// Colors

$aquamarine: #66CCC7;
$lightblue: #98BBDD;
$lightpurple: #E2A7C2;
$darkblue: #211F5C;
$green: #6C7E2A;
$lightgreen: #E6E4B3;
$black: #1F150A;
$orange: #FFB02E;
$lightorange: #FFB841;
$lightyellow: #F5FF66;
$lightbrown: #9F8170;
$darkgrey: #4C514A;

Стилей с этими цветами нигде нет, но такие решения часто используются для фоновых цветов, в таких случаях копируйте код отсюда:

.aquamarine {
  background-color: $aquamarine;
}

.lightblue {
  background-color: $lightblue;
}

.lightpurple {
  background-color: $lightpurple;
}
.darkblue {
  background-color: $darkblue;
}
.green {
  background-color: $green;
}
.lightgreen {
  background-color: $lightgreen;
}
.black {
  background-color: $black;
}
.orange {
  background-color: $orange;
}
.lightyellow {
  background-color: $lightyellow;
}
.lightbrown {
  background-color: $lightbrown;
}
.darkgrey {
  background-color: $darkgrey;
}

Сетка (container, layout, content, sidebar, col, row)

Сетка библиотеки построена на нескольких базовых принципах: скорость, легкость, доступность, унификация самых распространенных элементов на сайтах, адаптивность из коробки. На последнем остановимся.

Контейнерам container, layout, content и row - прописаны grid-правила, позволяющие начинать работу без базовой настройки сетки.

CSS - правила сетки описаны в файле ./src/styles/base/_general.scss, адаптация там же.

container (для проектов с фиксированной шириной контейнера)

! В сборке стоит по умолчанию в файле default.pug

Подключается в default.pug, над block header

Ширина контентной части

Нужен в случаях, когда необходим контейнер фиксированной ширины. Пример: ширина контентной части макета - max-width: 1300px.

Ширину контейнера container определяет переменная $container в ./src/styles/helpers/_variables.scss

Высота контентной части

Контейнер разделяет страницу на три части: шапку, контент и подвал. С помощью grid-template-rows: 80px minmax(75vh, 1fr) 80px;. В базовой верстке контейнера высота всех трех частей фиксированная. Это нужно для большей привлекательности и удобства верстки.

Но на боевой верстке самое удобное - поставить высоту шапки и подвала с помощью директивы auto. Таким образом контент будет принимать высоту содержимого.

адаптация container

В container прописано базовое свойство grid-template-columns: minmax(250px, $container);

При ширине экрана / окна меньше $container (по умолчанию 1300px), вступает в силу медиа-запрос на 1300px, добавляющий фиксированные padding: 0 $ind. Значение переменной $ind берется из _variables.scss

Таким образом реализуется адаптивность контейнера и контентной части сайта.

layout (для сайтов с элементами, выходящими за границы контентной части)

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

Подключается в default.pug, над block header

Ширина контентной части

Смысл этого контейнера в использовании в сочетании с классом layout-none. Если у вас в проекте присутствуют блоки, растягивающиеся на полную ширину окна, вроде фонов или слайдеров, layout поможет вам работать, не разбивая сайт на большое количество контейнеров. У вас будет один адаптируемый layout. А если нужно будет получить блок на всю ширину экрана, используйте какой-нибудь семантический тег в связке с layout-none, например: article.layout-none. Но очень важно, чтобы родительским элементом был именно layout.

Про расчет ширины контентной части. Формула такая:

Берем ширину контентной части из макета. Например, 1300px.

Вычисляем, сколько процентов эта ширина занимает от общей ширины, например от 1440px.
Полученный процент отнимаем от 100%. Результат - это сумма двух полей по бокам от макета.
Делим на два и вставляем получившееся значение в свойство margin-inline класс layout в _general.scss.

Более краткая формула

Ширина контента / ширина сайта * 100% = результат - 100% (получается совокупная ширина полей) ширина полей / 2 = margin-inline

Ширину отступов определяет переменная $layout-margin в _variables.scss. В качестве единицы измерения используем vw вместо %, чтобы ширина высчитывалась не из ширины контента, а из ширины окна.

Да, вы можете использовать абсолютные значения. Но vw гораздо удобнее.

Высота контентной части

Контейнер, как разделяет страницу на три части: шапку, контент и подвал. С помощью grid-template-rows: 80px minmax(75vh, 1fr) 80px;. В базовой верстке контейнера высота всех трех частей фиксированная. Это нужно для большей привлекательности и удобства верстки.

адаптация layout

Для адаптации ширины layout стоит использовать прописанное медиа-выражение, начинающееся с 1300px. По умолчанию в layout написан margin-inline: $layout-margin-mob. Это переменная из _variables.scss со значением по умолчанию 2vw.

content (контейнер контента после header и до footer)

Вспомогательный класс, содержащий grid-template-columns: minmax(200px, 2fr) и базовый gap. Нужен для того, чтобы обозначить контентную часть. Идёт после header.

Для напоминания структура общей колонки сайта grid-template-columns - .header / .content / .footer.

Он служит оберткой для всех семантических блоков контентной части сайта.

sidebar

Сперва подключим стили блока sidebar в _modules.scss: @import 'sidebar/sidebar';.

Контейнер сайдбара активируется в default.pug, над block content. Для того чтобы сайдбар заработал, добавьте content родительский класс content-sidebar.

Выглядеть это будет так:

block header
.content-sidebar
    .content
        block content

Затем надо добавить сам сайдбар в сетку, для этого добавьте выше или ниже content импорт БЭМ-блока include ../../blocks/modules/sidebar/sidebar.

block header
.content-sidebar
    include ../../blocks/modules/sidebar/sidebar
    .content
        block content

Нужен липкий контент в сайдбаре или просто контейнер для добавления контента? - предусмотрен класс sidebar__inner.

Сайдбар без отступа слева

Во многих проектах, вроде SPA-сайтов, сайдбар реализован без отступа слева, чтобы придать вид более цельного интерфейса. Для таких случаев реализована совместимость с layout-none.

Естественно, чтобы способ работал, надо, чтобы в default.pug основным контейнером был layout. А block content был обёрнут в тег с классом layout-none.

Активируется, если вы поместите элемент с классом content-sidebar внутрь layout-none. А стандартный вспомогательный класс content внутрь content-sidebar.

Теперь экран делится на две части. Сайдбар и контентную часть, которые тоже надо прописать. Вот так:

.layout-none
        .content-sidebar
            .sidebar
                .sidebar__inner
                    Some content in sidebar, maybe nav menu
            .content
                h1 Some content

адаптация sidebar

На данный момент есть базовая адаптация с отступами.

Но элемент sidebar имеет css-свойство height: 100%. А это значит, что растягивается он по максимальной ширине контента.

А поскольку в разных макетах сайдбары адаптируют по-разному, в первом коммите с сайдбаром никакой более продуманной адаптации пока не выполнено.

col

адаптация col

row

Если нужно сделать колонки с автоматической адаптацией - вставьте класс .row. Этот класс адаптирует до минимального размера экрана 320px.

Кстати, про количество колонок. Если колонки больше 320, они автоматически подстроятся под ширину экрана и ширину контента в колонках.

Руководство по стилю исполнения. Если намереваетесь использовать в одном из блоков row, добавляйте к названию блока __row по БЭМ.

SVG-спрайты

Для легкости работы с svg-спрайтами в ./src/views/helpers/mixins.pug существует миксин mixin sprite.

Использование в коде выглядит так:

  +sprite("class", "img/sprites/sprite.svg#svgname", width="value", height="value")

Компоненты

Подключение компонентов

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

Подключить его стили через ./src/blocks/components/_components.scss
Подключить скрипты, если блок их предусматривает через ./src/js/import/components.js

Компонент можно использовать, как подключив через include в pug, так и скопировав pug необходимые теги c css-классами. Иной раз важна иерархия классов, будьте внимательны при написании с нуля.

Вендорские стили и скрипты

В библиотеке есть два вендорских скрипта со стилями, реализованные через импорт:

Swiper Slider (component slider)
Fancybox (component gallery)
Gsap

Чтобы подключить скачанные вендорские скрипты, нужно вставить script(src="js/vendor.js")

в index.pug, в раздел block scripts, над main.js.

Где находятся эти импорты и как подключать самостоятельно новые библиотеки

Установка

yarn add <library>

Подключение

Импортировать библиотеку в js файле компонента ./src/blocks/components/component/component.js строчками вида import { name } from "path"; или import name { plugins } from "path";
Сохранить файл стилей подключаемой библиотеки в ./src/styles/vendor/import/... с названием вида _swiper.scss
Подключить файл стилей библиотеки в ./src/styles/vendor/_libs.scss

Список компонентов

Картинки (img)

Верстка

Подключение в index.pug: include ../blocks/components/img/img

Pug-файл компонента существует для примера, использовать его проще всего без импорта, а просто копируя верстку.

Главные два преимущества компонента img: возможность по умолчанию использовать object-fit и ленивая загрузка из коробки с атрибутами data-src и data-alt.

Object-fit

Картинка принимает ширину контейнера-родителя и автоматически адаптируется по правилам правила object-fit со свойством cover. Для работы object-fit у тега img или у изображения с другим классом / id должна быть задана явная высота height. Для этого можете на базовом уровне разместить картинку на странице так:

.img
  img(src="img/img.jpg" alt="Какая-то картинка")

Intersection observer API - lazy loading

Ленивая загрузка изображений в библиотеке подключена по умолчанию через импорт компонента img.js в components.js. Вам достаточно только совершить небольшие манипуляции с атрибутами изображения. Вместо атрибутов src и alt используйте атрибуты data-src и data-alt, как на примере:

.img
    img(data-src="img/img.webp" data-alt="Название картинки")

Intersection observer вытаскивает значения data-src и data-alt, и вставляет их в src и alt с этими значениями. Data-alt нужен для того, чтобы при загрузке страницы не возникал значок недостающего изображения на месте изображения, которое пока не подгрузилось.

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

Отступы

По умолчанию тег img имеет отступы сверху и снизу для более простой интеграции картинок в статьи и текстовые материалы. Чтобы отключить эту возможность, добавьте изображению класс .img__empty

Плейсхолдеры

Вы можете использовать плейсхолдеры из папки ./src/img/~, а можете удалить их.

Библиотеки

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

a.img#img-fancybox(data-fancybox="gallery" href="img/img.webp")
    img(src="img/img.webp")

CSS

Подключен в _components.scss, строчка @import 'img/img';

JS

Подключен в components.js, строчка import "%components%/img/img";

Кнопки (button)

Верстка

Кнопка сама по себе - элемент формы. Поэтому если хотите сделать из кнопки ссылку, оберните button в тег form с атрибутом action="ссылка"

CSS

По умолчанию у кнопки есть margin-block с отступами $ind (_variables.scss). Но если кнопка находится в form, отступы аннулируются, так как у тега form по умолчанию есть свои margin-block: $ind.

Формы (form)

Верстка

Все id и классы форм должны повторять название в type=""", либо название самого поля, как в случае с полем form. Исключение составляют теги label, где классы могут отличаться из-за особенностей верстки. Тег form стандартный, как было сказано выше, с .form и #form.

В случае, если в форме есть несколько полей, эти поля оборачиваются в класс form__grid, а каждое поле в класс form__grid--item.

Атрибут name="" в большинстве стандартных случаев для простоты стоит называть названием типа поля или его классов, id.

Отдельный случай поля type="checkbox", связанного с политикой конфиденциальности:

политика с чекбоксом заключается в класс form__privacy она уже стилизована в flex контейнер с корректным отображением
у label класс form__privacy--text, а ссылка под классом form__privacy--link

Переключатель как в IOS

Есть возможность привести type="checkbox" к виду переключателя, которые стали модны после появления в ios. Чтобы сделать такой переключатель, добавьте к checkbox класс и id checkbox-switch.

Остальной функционал стандартно согласно первым пунктам: название input и соответствующий класс с id.

CSS

Подключен в _components.scss, строчка @import 'form/form';

JS

Подключен в components.js, строчка import "%components%/form/form";

Таблицы (table)

Бургер (burger)

Важно! В js-файле компонента есть уже включенный пункт меню с dropdown - компонентом. Для избежания ошибок в консоли все функции, связанные с компонентом закомментированы.

Модальное окно (modal)

Верстка

Для подключения добавьте в default.pug ниже block footer строчку с: block modal. Затем в код страницы, например index.pug:

block footer
    include ../blocks/modules/footer/footer
      
block modal
    include ../blocks/components/modal/modal

block scripts...

Для того чтобы добавить кнопку - триггер модального окна, поместите атрибут data-modal к любой ссылке или кнопке на странице.

CSS

Подключение в _components.scss: добавить строчку @import 'modal/modal';

JS

Подключение в components.js: добавитьimport "%components%/modal/modal";.

Бесконечная прокрутка контента (infinite-scroll)

Для того чтобы встроить плагин в проект:

Подключите файлы стилей и скриптов, как на примере

Подключение в index.pug: include ../blocks/components/infinite-scroll/infinite-scroll

Флекс-галерея

Верстка

Подключение в любом блоке, типа main.pug: include ../../components/flex-gallery/flex-gallery

CSS

Подключение в _components.scss: раскомментировать @import 'flex-gallery/flex-gallery';

JS

Подключение в components.js: раскомментироватьimport "%components%/flex-gallery/flex-gallery";.

Раскрывающееся меню - список (dropdown)

Компонент нужен для создания выпадающего списка. Особенно он может быть полезным в создании меню сайта.

Верстка

Пока компонент заточен под ссылки и не рассчитан на дублирование. Поэтому использовать можно в любом блоке.

Для отступов внутри item-ов нужно задавать отдельные паддинги.

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

include ../components/dropdown/dropdown

и управлять компонентом в его папке.

Но для более детального управления можно скопировать код:

.dropdown
    p.dropdown__parent#dropdown-burger Материнский пункт
    .dropdown__items#dropdown-items
        div.dropdown__item
            a(href="#") Пункт
        div.dropdown__item
            a(href="#") Другой

Добавление списка в меню

Найдите pug-файл модуля header: ./src/blocks/modules/header/header, создайте там дополнительный элемент списка li.header-menu__item и вложите в него тот же код, приведённый выше.

CSS

Подключить в _components.scss, строчка @import 'dropdown/dropdown';

JS

Подключить в components.js, строчка import "%components%/dropdown/dropdown";

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

Работа с компонентом burger

При переходе на мобильную версию и появлении burger-меню, вы столкнётесь с тем, что по умолчанию dropdown не работает. Для этого необходимо пройти в js-файл компонента burger и раскомментируйте код, относящийся к dropdown.

Мультиязыковое меню + мини-плагин локализации для небольших сайтов (dropdown-lang)

Верстка

Подключение в header.pug: include ../../components/dropdown-lang/dropdown-lang

CSS

Подключение в _components.scss: раскомментировать @import 'dropdown-lang/dropdown-lang';

JS

Подключение в components.js: раскомментироватьimport "%components%/dropdown-lang/dropdown-lang";.

Слайдер Swiper c базовыми стилями и настройками (slider)

Внимание! Не помещайте слайдер в grid и flex-контейнеры, либо дорабатывайте слайдер под свои задачи

Слайдер Swiper с контентом, заходящим за край страницы и со скроллбаром (slide-beyond)

Верстка

Подключение в index.pug: include ../blocks/components/slider/slide-beyond

Внимание! Не помещайте слайдер в grid и flex-контейнеры, либо дорабатывайте слайдер под свои задачи

CSS

Подключение в _components.scss: раскомментировать @import 'slider/slider';

JS

Подключение в components.js: раскомментироватьimport "%components%/slider/slider";.

Табы в виде тегов (tabs-tags)

Хлебные крошки (breadcrumbs)

Квиз (quiz)

Текст с анимированным движением по кругу (circle)

Контейнер, выходящий за границы основной ширины макета (container-beyond)

Аккордеон (accordion)

Галерея (gallery)

Lightbox в галерее реализован через fancybox.

Верстка

Подключение в index.pug: include ../blocks/components/gallery/gallery

Для того чтобы активировать работу fancybox, напишите верстку такого вида:

a(data-fancybox="gallery" href="img/img.webp")
    img(src="img/img.webp")

CSS

Подключение в _components.scss: раскомментировать @import 'gallery/gallery';

JS

Подключение в components.js: раскомментироватьimport "%components%/gallery/gallery";.

Базовые настройки fancybox будут внутри.

README изначального репозитория gulp-pug-starter, на основе которого был создана библиотека tezis.components.

🔥 Особенности

именование классов по БЭМ
используется БЭМ-структура
используются препроцессоры Pug и SCSS
используется транспайлер Babel для поддержки современного JavaScript (ES6) в браузерах
используется Webpack для сборки JavaScript-модулей
используется жёсткий кодгайд
используется проверка кода на ошибки перед коммитом

🛠 Установка

установите NodeJS
установите глобально:
- Yarn: npm i -g yarn
- Gulp: npm i -g gulp
- Bem Tools: npm i -g bem-tools-core
скачайте сборку с помощью Git: git clone https://github.com/andreyalexeich/gulp-pug-starter.git
перейдите в скачанную папку со сборкой: cd gulp-pug-starter
введите yarn set version berry
скачайте необходимые зависимости: yarn
чтобы начать работу, введите команду: yarn run dev (режим разработки)
чтобы собрать проект, введите команду yarn run build (режим сборки)

Если вы всё сделали правильно, у вас должен открыться браузер с локальным сервером. Режим сборки предполагает оптимизацию проекта: сжатие изображений, минифицирование CSS и JS-файлов для загрузки на сервер.

📂 Файловая структура

gulp-pug-starter
├── dist
├── gulp-tasks
├── src
│   ├── blocks
│   ├── fonts
│   ├── img
│   ├── js
│   ├── styles
│   ├── views
│   └── .htaccess
├── gulpfile.babel.js
├── webpack.config.js
├── package.json
├── .yarnrc.yml
├── .babelrc.js
├── .bemrc.js
├── .eslintrc.json
├── .stylelintrc
├── .stylelintignore
└── .gitignore

Корень папки:
- .babelrc.js — настройки Babel
- .bemrc.js — настройки БЭМ
- .eslintrc.json — настройки ESLint
- .gitignore – запрет на отслеживание файлов Git'ом
- .stylelintrc — настройки Stylelint
- .stylelintignore – запрет на отслеживание файлов Stylelint'ом
- .yarnrc.yml – настройка Yarn
- gulpfile.babel.js — настройки Gulp
- webpack.config.js — настройки Webpack
- package.json — список зависимостей
Папка src - используется во время разработки:
- БЭМ-блоки и компоненты: src/blocks
- шрифты: src/fonts
- изображения: src/img
- JS-файлы: src/js
- страницы сайта: src/views/pages
- SCSS-файлы: src/styles
- служебные Pug-файлы: src/views
- конфигурационный файл веб-сервера Apache с настройками gzip (сжатие без потерь): src/.htaccess
Папка dist - папка, из которой запускается локальный сервер для разработки (при запуске yarn run dev)
Папка gulp-tasks - папка с Gulp-тасками

⌨️ Команды

yarn run lint:styles - проверить SCSS-файлы. Для VSCode необходимо установить плагин. Для WebStorm или PHPStorm необходимо включить Stylelint в Languages & Frameworks - Style Sheets - Stylelint (ошибки будут исправлены автоматически при сохранении файла)
yarn run dev - запуск сервера для разработки проекта
yarn run build - собрать проект с оптимизацией без запуска сервера
yarn run build:views - скомпилировать Pug-файлы
yarn run build:styles - скомпилировать SCSS-файлы
yarn run build:scripts - собрать JS-файлы
yarn run build:images - собрать изображения
yarn run build:webp - сконвертировать изображения в формат .webp
yarn run build:sprites- собрать спрайты
yarn run build:fonts - собрать шрифты
yarn run build:favicons - собрать фавиконки
yarn run build:gzip - собрать конфигурацию Apache
yarn run bem-m - добавить БЭМ-блок
yarn run bem-c - добавить компонент
yarn run lint:styles --fix - исправить ошибки в SCSS-файлах согласно настройкам Stylelint
yarn run lint:scripts - проверить JS-файлы
yarn run lint:scripts --fix - исправить ошибки в JS-файлах согласно настройкам ESLint.

💡 Рекомендации по использованию

Компонентный подход к разработке сайтов

каждый БЭМ-блок имеет свою папку внутри src/blocks/modules
папка одного БЭМ-блока содержит в себе один Pug-файл, один SCSS-файл и один JS-файл (если у блока используется скрипт)
- Pug-файл блока импортируется в файл src/views/index.pug (или в необходимый файл страницы, откуда будет вызываться блок)
- SCSS-файл блока импортируется в файл src/blocks/modules/_modules.scss
- JS-файл блока импортируется в src/js/import/modules.js

Пример структуры папки с БЭМ-блоком:

blocks
├── modules
│   ├── header
│   │   ├── header.pug
│   │   ├── header.js
│   │   ├── header.scss

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

yarn run bem-m my-block - для создания БЭМ-блока в src/block/modules (для основных БЭМ-блоков), где my-block - имя БЭМ-блока (после создания нужно удалить содержимое js-файла БЭМ-блока);
yarn run bem-с my-component - для создания компонента в src/blocks/components (для компонентов), где my-component - имя компонента (после создания нужно удалить содержимое js-файла БЭМ-компонента);

Компоненты

компоненты (например, иконки, кнопки) оформляются в Pug с помощью примесей
каждый компонент имеет свою папку внутри src/blocks/components
папка одного компонента содержит в себе один Pug-файл, один SCSS-файл и один JS-файл (если у компонента используется скрипт)
- Pug-файл компонента импортируется в файл главной страницы src/views/index.pug (или в необходимый файл страницы, откуда будет вызываться компонент)
- SCSS-файл компонента импортируется в файл src/blocks/components/_components.scss
- JS-файл компонента импортируется в файл src/js/import/components.js

Страницы проекта

страницы проекта находятся в папке src/views/pages
- каждая страница (в том числе главная) наследует шаблон src/views/layouts/default.pug
- главная страница: src/views/index.pug

Шрифты

шрифты находятся в папке src/fonts
- используйте форматы .woff и .woff2
- шрифты подключаются в файл src/styles/base/_fonts.scss
- сконвертировать локальные шрифты можно с помощью данного сервиса

Адаптация

Если по проекту и макету нет четкого гайдлайна, в body стоит адаптивный шрифт. За основу берется браузерный стандарт 16px. Минимальный шрифт 0.9rem (14.4px), максимальный - 1rem (ну, собственно, 16px). Ширина экрана, на которой меняется шрифт - от 768px до 1024px.

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

Шрифты лучше перераспределять с 16px в html {} на 14px на брейкпоинте, означающем переход на размер мобильных устройств

Изображения

изображения находятся в папке src/img
- изображения автоматически конвертируются в формат .webp. Подробная информация по использованию тут
- изображение для генерации фавиконок должно находиться в папке src/img/favicon и иметь размер не менее 1024px x 1024px

SVG-спрайты

Для создания спрайтов изображения .svg должны находиться в папке src/img/sprites. Например, у нас есть файлы icon-1.svg, icon-2.svg и icon-3.svg, и мы должны обратиться к icon-2.svg. Для этого в HTML нужно воспользоваться тегом use:

svg
    use(xlink:href="img/sprites/sprite.svg#logo")

Изменить стили svg-иконки из спрайта в CSS:

svg use {
  fill: red;
}

Бывает такая ситуация, когда стили иконки поменять не получается. Это связано с тем, что при экспорте из Figma в svg добавляется лишний код. Например:

<svg width="18" height="19" viewBox="0 0 18 19" fill="none" xmlns="http://www.w3.org/2000/svg">
  <path d="M4.90918 4.04542L13.091 9.54088L4.90918 14.9545L4.90918 4.04542Z" fill="#1B1B1D"/>
</svg>

Нужно удалить fill="none" и fill="#1B1B1D". Должно получиться так:

<svg width="18" height="19" viewBox="0 0 18 19" xmlns="http://www.w3.org/2000/svg">
  <path d="M4.90918 4.04542L13.091 9.54088L4.90918 14.9545L4.90918 4.04542Z"/>
</svg>

Cторонние библиотеки

все сторонние библиотеки устанавливаются в папку node_modules
- для их загрузки воспользуйтесь командой yarn add package_name
- для подключения JS-файлов библиотек импортируйте их в самом начале JS-файла БЭМ-блока (то есть тот БЭМ-блок, который использует скрипт), например:
```
import $ from "jquery";
```
- для подключения стилевых файлов библиотек импортируйте их в файл src/styles/vendor/_libs.scss
- JS-файлы и стилевые файлы библиотек самостоятельно изменять нельзя

👉 Нужен SCSS без Pug?

Используйте эту сборку.

💛 Нравится проект?

Сообщайте мне о багах, ставьте звёздочку в правом верхнем углу, задонатьте мне на пиво 🍺

✉️ Контакты

По всем вопросам пишите в Telegram

tarchevsky / anamnesis-project Goto Github PK

anamnesis-project's Introduction

tezis.components

Если просто

Если подробнее

Переиспользование, универсальность

Доступность

Верстка

CSS

JS

Дополнительные переменные цвета

Ширина контентной части

Высота контентной части

адаптация container

Ширина контентной части

Высота контентной части

адаптация layout

Сайдбар без отступа слева

адаптация sidebar

адаптация col

Где находятся эти импорты и как подключать самостоятельно новые библиотеки

Установка

Подключение

Список компонентов

Верстка

Object-fit

Intersection observer API - lazy loading

Отступы

Плейсхолдеры

Библиотеки

CSS

JS

Верстка

CSS

Верстка

Переключатель как в IOS

CSS

JS

Верстка

CSS

JS

Верстка

CSS

JS

Верстка

Добавление списка в меню

CSS

JS

Работа с компонентом burger

Верстка

CSS

JS

Верстка

CSS

JS

Табы в виде тегов (tabs-tags)

Хлебные крошки (breadcrumbs)

Квиз (quiz)

Текст с анимированным движением по кругу (circle)

Контейнер, выходящий за границы основной ширины макета (container-beyond)

Аккордеон (accordion)

Галерея (gallery)

Верстка

CSS

JS

Семантические теги и за что они отвечают

🔥 Особенности

🛠 Установка

📂 Файловая структура

⌨️ Команды

💡 Рекомендации по использованию

Компонентный подход к разработке сайтов

Адаптация

👉 Нужен SCSS без Pug?

💛 Нравится проект?

✉️ Контакты

anamnesis-project's People

Contributors

Watchers

Recommend Projects