Руководство
Это руководство описывает SIMAI Framework целиком: что это такое, как он устроен, как его подключить и обновлять, из чего складывается внешний вид, как работают утилиты, компоненты, Smart-компоненты и макеты и какие стандарты и проверки обеспечивают их согласованность.
Что это за документ
Руководство объясняет устройство Framework: зачем нужна каждая часть, как она работает и как связана с остальными. Это не справочник.
- Полные списки классов, токенов, настроек и событий находятся в справочниках документации: «Утилиты», «Компоненты», «Smart-компоненты» и справочнике токенов.
- Количества, которые меняются от поставки к поставке (сколько компонентов, токенов, страниц), в тексте не приводятся. Их показывают справочники.
- В тексте используются только канонические имена классов, атрибутов, событий и токенов. Как Framework сообщает об устаревших именах и как перевести на канонические имена существующий проект, описано на страницах Жизненный цикл изменений и Как обновить проект.
Как читать
Части идут от простого к сложному: что это → как подключить → из чего состоит вид → как применять его классами → компоненты → Smart-компоненты → композиция страниц → стандарты и проверки.
| Читатель | Разделы |
|---|---|
| Все | Знакомство и Подключение и обновление |
| Те, кто пишет разметку и оформление | Токены, цвет и темы, Размер, пространство, текст и форма, Утилиты и раскладка |
| Те, кто работает с компонентами и пишет их | Компоненты и Smart-компоненты |
| Те, кто собирает страницы из данных | Макеты и композиция |
| Авторы Framework, проверяющие, пользователи ИИ-инструментов | Стандарты, качество и ИИ |
Карта частей с кратким содержанием — в Карта руководства.
Условные обозначения
- Перекрёстные ссылки ведут на страницу и её раздел и называют его заголовок: «см. Соразмерные ступени».
- Термины определяются при первом появлении и собраны в глоссарии. Одно понятие во всём тексте называется одним термином.
- Правила записаны списками со словами «обязательно», «нельзя», «рекомендуется».
- Код в примерах полный и рабочий; перед примером сказано, что он показывает, после — что в нём важно заметить.
Карта руководства
Части идут от простого к сложному: что это → как подключить → из чего состоит вид → как применять его классами → компоненты → Smart-компоненты → композиция страниц → правила и проверки.
| Раздел | О чём | Кому особенно нужен |
|---|---|---|
| Знакомство | Что такое Framework, уровни, граница с проектом, быстрый старт | Всем |
| Подключение и обновление | Loader, пакеты компонентов, CDN и свои файлы, выпуски и их закрепление, жизненный цикл изменений | Тем, кто подключает и обновляет |
| Токены, цвет и темы | Примитивы и роли, палитры, цветовые роли, прозрачность, контраст, высота, темы, каскадные слои | Верстальщикам и дизайнерам |
| Размер, пространство, текст и форма | Шкалы, лестница размеров, адаптивные размеры, отступы, типографика, границы, радиусы, фокус, направление письма, язык | Верстальщикам и дизайнерам |
| Утилиты и раскладка | Синтаксис утилит, значения, условия, классы раскладки | Всем, кто пишет разметку |
| Компоненты | Компоненты на классах: анатомия, имена настроек, размеры, состояния, поля форм | Разработчикам интерфейса |
| Smart-компоненты | Собственные теги с поведением: свойства, шаблоны, события, состояния, составные компоненты, порты хоста, манифест | Разработчикам интерфейса и авторам компонентов |
| Макеты и композиция | Страница как данные: документ, сборка, блоки, источники данных, редактор | Тем, кто собирает страницы из данных и CMS |
| Стандарты, качество и ИИ | Что обязано быть правдой, проверки Framework и проекта, работа с ИИ | Авторам Framework, проверяющим, пользователям ИИ |
| Глоссарий | Термины руководства | По необходимости |
Пример маршрута
Каталог товаров, например, изучают по такому маршруту:
- подключить Framework;
- понять уровни Framework;
- выбрать утилиты и компоненты для карточек;
- добавить Smart-компоненты для фильтров и других изменяемых состояний;
- описать страницу макетом, если её структуру нужно хранить как данные.
Руководство — это теория: оно объясняет, зачем вещь, как устроена и как связана с остальным. Полные списки классов, токенов, настроек и событий находятся в справочниках документации: «Утилиты», «Компоненты», «Smart-компоненты».