TurboExtensions

Расширенные возможности стилизации средствами CSS.

Инструменты разработчика

DevServer

Пререквизиты — node.js 8.x или nvm.

Установка:

git clone https://github.com/turboext/css.git
cd css
npm install
npm start

Локальный запуск тестов — npm test.

Возможности:

автоматическое применение стилей без необходимости перезагружать страницу
возможность открыть локальную бету на мобильном телефоне
написание стилей в синтаксисе CSS или SCSS с использованием препроцессора postcss.

Использование:

Допустим, вы хотите поменя стили для сайта https://rozhdestvenskiy.ru. Порядок действий следующий:

создать директорию hosts/rozhdestvenskiy.ru (дальше все действия будут происходить внутри этой директории);
внутри этой директории создать файл HOSTS.yaml
указать там название домен сайта, который используется в турбо-страницах:

- https://rozhdestvenskiy.ru

создать файл style.css или style.scss
запустить dev-server
открыть http://localhost:3000 и выбрать адрес вашей турбо-страницы, например: https://rozhdestvenskiy.ru/, или https://yandex.ru/turbo?text=https://rozhdestvenskiy.ru/;
внести изменения в файл стилей;
изменения стилей будут применены автоматически.

Дополнительные возможности DevServer

TURBO_HOST=https://some-host.yandex.ru npm start — возможность ходить за данными на отличный от https://yandex.ru сервер;
&hostname=https://example.com — форсировать применение стилей для выбранного хоста, даже если url турбо-страницы отличается от него;
&disable=1 — отключить подмену CSS (может быть удобно для тестирования страницы в iframe).

Livereload

По-умолчанию включён livereload режим, в котором изменения применяются автоматически без обновления страницы. Если с ним возникают сложности, нужно запустить сервер с переменной окружения LIVERELOAD=false:

mac os x / linux — LIVERELOAD=false npm start
windows — set LIVERELOAD=false && npm start

Отладка на мобильном телефоне

Существует два варианта:

дождаться сборки автоматической беты в PR и использовать ссылки из описания PR
для доступа к локальной бете с мобильного телефона можно использовать встроенное тунеллирование на базе ngrok:
- mac os x / linux — PUBLIC=true npm start или npm run public
- windows — set PUBLIC=true && npm start или npm run public

IFrame

Турбо-страницы могут отображаться внутри iframe, например в Поиске, поэтому рекомендуется смотреть на результат изменения стилей в iframe. В случае изменения каркаса страницы, могут возникнуть проблемы наличием горизонтального скролла. Убрать его можно следующим образом:

.ua_frame_yes .page__container {
    overflow-x: hidden;
}

Для тестирования страницы внутри iframe — нужно использовать адрес /frame, /frame-morda, вместо /turbo. Ссылки на iframe будут доступны в PR.

Прототипирование стилей в браузере

Установить расширенение live editor for CSS (или любое другое с похожими возможностями);
Зайти в браузере на турбо-страницу;
Написать CSS для нужных компонентов.

Ограничения

Ограничения указаны в конфиге stylelint:

нельзя использовать пользовательские шрифты;
нельзя использовать низкопроизводительную анимацию;
нельзя использовать селекторы по имени тэга;
нельзя использовать любые внешние ресурсы;
размер CSS в gzip ограничен 21KB.

Deprecated

Селекторы на .markup и его производные в скором времени перестанут работать

На code review могут быть указаны дополнительные требования к коду.

Важно: список ограничений может меняться со временем.

Технические детали сборки

CSS код будет обработан с помощью postcss. Настройки можно посмотреть в конфигурационном файле.
Минимальные версии поддерживаемых браузеров
- android 4
- iOS 9
- IE 11
Векторные изображения предпочтительнее растровых. Размер всех изображений должен быть оптимизирован до приемлемого уровня качества.

Для оптимизации SVG рекомендуется использовать svgo со следующими опциями: svgo -p 2 --multipass --enable=removeDesc --enable=removeTitle --enable=sortAttrs --enable=removeViewBox --enable=removeStyleElement -i [PATH_TO_SVG].

Создание PR

Сделать fork репозитория;
Создать директорию hosts/example.com;
В директории должно быть несколько обязательных файлов — HOSTS.yaml, OWNERS.yaml, style.css. Возможен вариант style.scss для использования синтаксиса SCSS.
- HOSTS.yaml должен быть указан домен для которых будут применяться текущие стили, например:
```
- https://rozhdestvenskiy.ru
```
Протокол (http, https) обязателен. Фактически, это адрес сайта из https://webmaster.yandex.ru
- OWNERS.yaml должен содержать список логинов на https://github.com кому разрешено править стили для текущего домена, например:
```
- sbmaxx
```
Закоммитить изменения и создать PR в основной репозиторий. Желательно в тексте коммита указывать адрес сайта;
В описании PR добавьте несколько ссылок на ваши турбо-страницы;
Дождитесь создания автоматической беты. Ссылка на неё появится в описании PR через некоторое время после создания PR, проверьте на ней свои изменения;
Дождитесь прохождения линтеров;
Дождитесь прохождения ревью;

Когда я увижу это в production?

Изменения будут доступны в production в течение 30 минут после вливания PR в master ветку. В случае возникновения каких-либо проблем, пишите в slack, мы сможем помочь оперативно откатить изменения или внести правки.

Внесение изменений в инфраструктурную часть

Создать issue с описанием сути изменений;
Сделать branch в формате issues/<номер_issue>;
Закоммитить изменения и создать PR в основной репозиторий;
Связать PR и issue (например, c помощью комментария).

Поддержка разработчиков

https://turbosupport.slack.com, доступ по приглашениям.

krawster/css