From 7554ce58dbcb6112a60ec2c92503ce83731b1b61 Mon Sep 17 00:00:00 2001 From: "S.Gromov" Date: Wed, 13 May 2026 11:20:14 +0300 Subject: [PATCH] =?UTF-8?q?feat:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8E=20=D0=BF=D0=BE=20Figma=20Adaptive=20St?= =?UTF-8?q?andards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - добавлены исходные материалы канона по адаптивным макетам - добавлена конфигурация VitePress для новой документации - подключена сборка документации в npm-скриптах, CI и Docker - обновлена карточка документации на главной странице --- .dockerignore | 1 + .gitea/workflows/ci.yml | 3 + .gitignore | 1 + Dockerfile | 2 +- .../adaptive-layout-requirements.checklist.md | 138 +++++ .../adaptive-layout-requirements.full.md | 473 ++++++++++++++++++ .../adaptive-layout-requirements.short.md | 156 ++++++ canons/figma/index.md | 30 ++ .../.vitepress/config.ts | 19 + docs/figma-adaptive-standards/docs.config.ts | 33 ++ package.json | 2 + src/config/docs.config.ts | 3 +- 12 files changed, 859 insertions(+), 2 deletions(-) create mode 100644 canons/figma/adaptive-layout-requirements.checklist.md create mode 100644 canons/figma/adaptive-layout-requirements.full.md create mode 100644 canons/figma/adaptive-layout-requirements.short.md create mode 100644 canons/figma/index.md create mode 100644 docs/figma-adaptive-standards/.vitepress/config.ts create mode 100644 docs/figma-adaptive-standards/docs.config.ts diff --git a/.dockerignore b/.dockerignore index ae8aa6d..3f92740 100644 --- a/.dockerignore +++ b/.dockerignore @@ -7,6 +7,7 @@ docs/*/.vitepress/cache docs/*/.vitepress/dist docs/*/content public/slm-design +public/figma-adaptive-standards *.log .DS_Store .env* diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index c1094a0..9a2f7db 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -23,6 +23,9 @@ jobs: - name: Сборка документации SLM Design run: npm run docs:build:slm-design + - name: Сборка документации Figma Adaptive Standards + run: npm run docs:build:figma-adaptive-standards + - name: Генерация корневых артефактов run: npm run site:generate diff --git a/.gitignore b/.gitignore index 8f858d5..84eaefb 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ docs/*/content/ docs/*/.vitepress/cache/ public/llms.txt public/slm-design/ +public/figma-adaptive-standards/ # Editor directories and files .vscode/* diff --git a/Dockerfile b/Dockerfile index aee6059..1804b29 100644 --- a/Dockerfile +++ b/Dockerfile @@ -6,7 +6,7 @@ COPY package*.json ./ RUN npm ci COPY . . -RUN npm run docs:build:slm-design && npm run build +RUN npm run docs:build:slm-design && npm run docs:build:figma-adaptive-standards && npm run build FROM caddy:2-alpine diff --git a/canons/figma/adaptive-layout-requirements.checklist.md b/canons/figma/adaptive-layout-requirements.checklist.md new file mode 100644 index 0000000..edd574a --- /dev/null +++ b/canons/figma/adaptive-layout-requirements.checklist.md @@ -0,0 +1,138 @@ +# Чеклист приёмки макета (Figma) + +> Примечание: в этом чеклисте «обоснованно» означает: по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`, `Stretch/Center`) понятно **что выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. Если без пояснения можно понять по-разному — добавлена аннотация/комментарий. + +## 0. Структура файла и нейминг +- [ ] В файле есть рабочие страницы: Cover / Overview, Design / UI, Components, Styles / Tokens, Responsive / Breakpoints, Prototype (Archive / Old — при необходимости) +- [ ] Экраны названы по единому правилу (например: `Feature / Screen — Breakpoint`) +- [ ] Компоненты названы семантически и единообразно (без «Button 1 / Button 2») +- [ ] На странице `Responsive / Breakpoints` описаны правила перестроения для сложных зон (колонки, переносы, скрытие/появление элементов) + + + +## 1. Брейкпоинты +- [ ] Все якорные брейкпоинты созданы в виде отдельных фреймов + - Mobile, Mobile Wide, Tablet, Laptop, Desktop (диапазоны соблюдены) +- [ ] Границы диапазонов трактуются единообразно (например: `Mobile ≤ 479`, `Mobile Wide 480–767`, `Tablet 768–1023`, `Laptop 1024–1439`, `Desktop ≥ 1440`) +- [ ] Фреймы логически и визуально связаны +- [ ] Дополнительные фреймы есть только при изменении сетки, навигации или структуры контента + + + +## 2. Адаптивность и ресайз +- [ ] Ресайз фрейма вручную до минимального значения диапазона +- [ ] Ресайз фрейма до максимального значения диапазона +- [ ] Проверены промежуточные значения (минимум 3–5 точек внутри диапазона) +- [ ] Макет корректно меняется во всём диапазоне без создания дублирующих фреймов +- [ ] Нет коллизий при ресайзе (наезды, обрезания, неожиданные перекрытия) +- [ ] Карточки и блоки тянутся или сжимаются корректно +- [ ] Текст переносится/обрезается по правилам и не выходит за пределы контейнеров +- [ ] Навигация корректно адаптируется под ширину + + + +## 3. Auto Layout и Constraints +- [ ] Все контейнеры, списки, карточки, кнопки, хедеры, футеры, сайдбары используют Auto Layout +- [ ] Padding задан со всех сторон через Auto Layout (без «ручных» отступов) +- [ ] Spacing между элементами задан через Auto Layout +- [ ] Режимы ресайза выбраны обоснованно (`Hug / Fill / Fixed`) для ключевых контейнеров и элементов +- [ ] При необходимости заданы min/max (для предотвращения поломок на крайних ширинах) +- [ ] Constraints заданы корректно (Left / Right / Top / Bottom / Center / Scale) там, где Auto Layout не покрывает сценарий +- [ ] Нет ручного позиционирования или абсолютных размеров без причины + + + +## 4. Сетка / Layout Grid +- [ ] Layout Grid настроен на фреймах каждого брейкпоинта (колонки соответствуют принятому стандарту) +- [ ] Margin и gutter заданы и согласованы с версткой +- [ ] Поведение сетки выбрано обоснованно (Stretch/Center — по модели проекта) +- [ ] Основные блоки выровнены по сетке и используют согласованный шаг отступов + + + +## 5. Компоненты +- [ ] Все повторяющиеся элементы оформлены как Components +- [ ] Используются Variants вместо копий +- [ ] Состояния компонентов показаны (минимум: Default, Hover, Active/Pressed, Disabled, Focus — если применимо) +- [ ] Компоненты корректно тянутся и меняют высоту по контенту +- [ ] Адаптивное поведение проверено во всех типовых контейнерах (экран, модалка, сайдбар, список/сетка) + + + +## 6. Типографика +- [ ] Используются Text Styles (`H1 / H2 / Body / Caption / Button` или принятый набор) +- [ ] Используются только бесплатные шрифты (предпочтительно Google Fonts) +- [ ] Есть коллекция Variables для типографики и Modes под брейкпоинты (например: Mobile/Mobile Wide/Tablet/Laptop/Desktop — как принято в проекте) +- [ ] Text Styles используют переменные типографики (минимум размер и line-height; при необходимости letter-spacing) +- [ ] На фреймах установлен корректный Mode для соответствующего брейкпоинта +- [ ] Ограничение количества строк соблюдено там, где это критично +- [ ] Правила для текста определены: перенос или обрезка (truncate), поведение при переполнении проверено +- [ ] Проверены «экстремальные» тексты, включая одну очень длинную строку без пробелов + + + +## 7. Цвета и стили +- [ ] Все цвета через Color Styles +- [ ] Семантические названия соблюдены (`Primary / Secondary`, `Text / Background / Border`, `Success / Error / Warning`) +- [ ] Дополнительные стили (тени/обводки/радиусы), если используются, применены единообразно + + + +## 8. Контент и состояния UI +- [ ] Текст проверен на короткие / нормальные / длинные варианты +- [ ] Проверка переполнения и переноса строк выполнена +- [ ] Состояния UI присутствуют: Default, Hover, Active, Disabled, Focus, Loading, Empty, Error +- [ ] Для форм/инпутов показаны состояния ошибок и валидации (включая сочетания вроде `Focus + Error`, если применимо) + + + +## 9. Изображения и медиа +- [ ] Fill / Fit задан корректно +- [ ] Safe area для обрезки изображений соблюдена +- [ ] Поддерживаются разные соотношения сторон (описано поведение при изменении ratio) +- [ ] Форматы и размеры соответствуют требованиям проекта (если есть требования к экспорту) + + + +## 10. Навигация +- [ ] Desktop → горизонтальное меню +- [ ] Tablet → сокращённое меню +- [ ] Mobile → бургер / bottom bar +- [ ] Описаны правила overflow/сокращения (что уходит в «ещё», что скрывается/переезжает) + + + +## 11. Accessibility (A11y) +- [ ] Контраст ≥ WCAG AA +- [ ] Минимальный размер клика 44×44 px +- [ ] Focus states проверены +- [ ] Логичный tab order соблюден + + + +## 12. Прототипирование +- [ ] Основные пользовательские флоу представлены +- [ ] Переходы между брейкпоинтами реализованы (если требуется) +- [ ] Поведение при ресайзе проверено/продемонстрировано + + + +## 13. Передача в разработку +- [ ] Dev Mode включён +- [ ] Все комментарии с логикой адаптивности оставлены +- [ ] Брейкпоинты, поведение блоков, скрытие/появление элементов описаны +- [ ] Ассеты к экспорту подготовлены (если требуется): корректные имена, форматы, настройки экспорта + + + +## 14. Запрещено +- [ ] Фиксированные ширины без причины +- [ ] Дубли компонентов под каждый экран +- [ ] Текст как вектор +- [ ] Ручные отступы +- [ ] Отсутствие Auto Layout + + + +## ✅ Итоговое решение +Макет считается **готовым к разработке**, если выполнены все пункты чеклиста и ресайз работает корректно во всех диапазонах. diff --git a/canons/figma/adaptive-layout-requirements.full.md b/canons/figma/adaptive-layout-requirements.full.md new file mode 100644 index 0000000..5d48d28 --- /dev/null +++ b/canons/figma/adaptive-layout-requirements.full.md @@ -0,0 +1,473 @@ +# Требования к адаптивному дизайну в Figma (Полная версия) + +Документ описывает стандарт подготовки **адаптивных** макетов в Figma так, чтобы они: + +- корректно **ресайзились** в пределах заданных диапазонов ширин; +- были **предсказуемы** для разработки (верстки); +- минимизировали количество «ручных» правок и дублирования; +- содержали достаточные пояснения по поведению UI. + +## Кому адресовано +- Дизайнерам интерфейсов +- Team Lead / DesignOps +- Разработчикам (для валидации качества и передачи в работу) + +## Термины (коротко) +- **Брейкпоинт** — якорная ширина и набор правил компоновки, по которым интерфейс меняет структуру. +- **Диапазон** — интервал ширин, где **один** макет обязан работать корректно при ресайзе. +- **Auto Layout** — основной механизм адаптивности в Figma для контейнеров и компонентов. +- **Hug / Fill / Fixed** — режимы ресайза (по контенту / заполнять контейнер / фиксированно). +- **Constraints** — привязки объектов внутри Frame (Left/Right/Top/Bottom/Center/Scale). +- **«Обоснованно» (в контексте этого стандарта)** — по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`, `Stretch/Center`) должно быть понятно: **что именно выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. Если выбор может трактоваться по-разному — добавьте аннотацию/комментарий на странице `Responsive / Breakpoints`. + + + +## 1. Структура файла Figma + +### 1.1. Цель структуры +Структура страниц нужна для: +- быстрого поиска актуальных экранов и компонентов; +- отделения финального UI от пояснений по адаптивности и интерактивности; +- прозрачной передачи в разработку. + +### 1.2. Рекомендуемая структура страниц +- **Cover / Overview** — контекст: цель продукта, аудитория, платформы, контакты, ссылки, правила +- **Design / UI** — финальные экраны (по брейкпоинтам или по флоу) +- **Components** — библиотека компонентов и их состояния/варианты +- **Styles / Tokens** — стили: цвет, типографика, эффекты, сетки (если принято) +- **Responsive / Breakpoints** — правила поведения, схемы перестроения, примеры ресайза +- **Prototype** — интерактивные сценарии и пользовательские флоу +- **Archive / Old** — устаревшие версии (только для истории) + +> Примечание: `Responsive / Breakpoints` и `Prototype` **не дублируют** финальные экраны один-в-один. Их задача — объяснить поведение, которое не очевидно из статичных макетов. + +### 1.3. Правила нейминга (минимальный стандарт) +- Страницы: `Design / UI`, `Components` и т.д. — одинаково во всех проектах. +- Фреймы экранов: `Feature / Screen — Breakpoint` (например: `Catalog / List — Desktop`) +- Компоненты: `ComponentName` + группа (`Button / Primary`, `Input / TextField`), семантика важнее внешнего вида. + +### 1.4. Что считается «готовым набором» в файле +В файле должны быть: +- фреймы всех якорных брейкпоинтов; +- компоненты и их состояния (через Variants); +- стили (цвета/типографика) с семантическими именами; +- пояснения по адаптивности и «порогам» изменений. + + + +## 2. Брейкпоинты и адаптивность + +### 2.1. Якорные брейкпоинты (база) +| Версия | Размер макета (Frame) | Диапазон ресайза | +|-------------|----------------|---------------| +| Mobile | 375 px | 360 – 479 px | +| Mobile Wide | 560 px | 480 – 767 px | +| Tablet | 992 px | 768 – 1023 px | +| Laptop | 1280 px | 1024 – 1439 px| +| Desktop | 1640 px | 1440 – 1920 px| + +Требования: +- Каждый брейкпоинт — отдельный **Frame** (Screen Frame). +- Диапазоны рассматриваются как **интервалы ресайза**: макет должен работать от min до max. +- Все брейкпоинты должны быть **логически и визуально связаны**: типографика, сетка, шаги отступов и компоненты должны «эволюционировать», а не пересобираться хаотично. + +> Примечание про границы: диапазоны заданы без пересечений. Пороговые значения: 480/768/1024/1440. Пример правила: `Mobile ≤ 479`, `Mobile Wide 480–767`, `Tablet 768–1023`, `Laptop 1024–1439`, `Desktop ≥ 1440`. + +### 2.2. Когда допустимо менять список брейкпоинтов +Базовый набор можно корректировать **только** при объективной необходимости: +- меняется **навигационный паттерн** (например, горизонтальное меню → бургер); +- меняется **сетка** (количество колонок/маржины/контейнер); +- меняется **иерархия контента** (скрытие/появление блока, перестановка основных зон); +- появляются «скачки» из-за контента, которые нельзя закрыть корректным ресайзом. + +Недопустимая причина: +- «так удобнее рисовать» или «не получилось настроить авто-лейаут». В этом случае исправляется настройка, а не множатся фреймы. + +### 2.3. Принцип «один фрейм — один диапазон» +Один фрейм описывает **поведение интерфейса в диапазоне**, а не конкретное устройство. + +Дополнительный фрейм внутри диапазона создаётся только если: +- на определённой ширине меняется **структура** (например, 2 колонки → 3 колонки); +- меняется **тип навигации**; +- меняется **композиция** ключевых зон (например, фильтры из сайдбара уходят в drawer). + +### 2.4. Обязательное требование: корректный ресайз +Макет считается адаптивным только если он корректно ресайзится вручную **во всём диапазоне**. + +Проверка (обязательная): +- вручную измените ширину фрейма до **минимума** диапазона; +- вручную измените ширину фрейма до **максимума** диапазона; +- проверьте промежуточные значения (минимум 3–5 точек внутри диапазона). + +Оценивается: +- поведение сетки и контейнеров; +- перенос и переполнение текста; +- колонки, карточки и списки; +- навигация и хедер/футер; +- отсутствие коллизий: наездов, обрезаний, неожиданных перекрытий; +- сохранение визуальной иерархии. + +> Макет некорректен, если «работает» только на базовой ширине, а при ресайзе ломается. + +### 2.5. Реализация адаптивности в Figma (обязательные правила) + +#### 2.5.1. Auto Layout +Обязателен для: +- всех контейнеров списков и лент; +- карточек, таблиц, форм; +- хедера/футера/сайдбара; +- любых повторяющихся групп (где есть паддинги и расстояния). + +Минимальные требования к Auto Layout: +- паддинги задаются через Auto Layout (а не «ручными» прямоугольниками); +- расстояния между элементами задаются через `Spacing`; +- направление (Horizontal/Vertical) и `Wrap` выбираются обоснованно; +- в ключевых местах задаются **min/max** (если без этого появляются «переломы» компоновки). + +#### 2.5.2. Resizing: Hug / Fill / Fixed +Правила выбора: +- **Контейнеры** (строки, колонки, секции) чаще всего: `Fill container` по ширине. +- **Элементы по контенту** (лейблы, чипсы, иконки): `Hug contents`. +- **Фиксированные размеры** — только для: + - иконок (например, 16/20/24); + - интерактивных областей, где фикс диктуется UX (например, высота кнопки); + - медиа с заданным форм-фактором (но с контролем кропа). + +Типичная ошибка: «всё Fixed». Это убивает адаптивность. + +#### 2.5.3. Constraints +Constraints применяются там, где Auto Layout не покрывает сценарий (например, декоративные элементы, фоновые иллюстрации, абсолютные позиционирования). + +Минимальные правила: +- элемент, который должен «прилипать» к краю контейнера, получает соответствующие привязки (`Left/Right/Top/Bottom`); +- элементы, которые должны масштабироваться пропорционально, используют `Scale` только если это оправдано (иначе деформируется типографика и иконки); +- избегайте смешения: Auto Layout внутри контейнера + хаотичные constraints у детей. + +### 2.6. Примеры адаптивного поведения (как описывать) +В странице `Responsive / Breakpoints` для каждой сложной зоны должны быть описаны правила в формате: +- **Что фиксировано** (например, высота хедера 64px) +- **Что тянется** (контейнер контента по ширине) +- **Что переносится/перестраивается** (карточки wrap, 1→2→3 колонки) +- **Что скрывается/появляется** (например, вторичный CTA скрывается на mobile) + +Пример описания (текстом): +- «Сетка карточек: на Mobile — 1 колонка, на Tablet — 2 колонки, на Laptop/ Desktop — 3 колонки. Карточка имеет min-width 280px, при нехватке места переносится на новую строку (wrap).» + + + +## 3. Компоненты + +### 3.1. Что обязано быть компонентом +Компонентами должны быть оформлены: +- любые повторяющиеся UI-элементы (кнопки, поля, карточки, бейджи, таблицы, модалки); +- сложные блоки, встречающиеся минимум 2 раза; +- элементы с состояниями/интерактивностью. + +Запрещено: +- копировать элементы «вручную» вместо компонентов; +- создавать отдельные компоненты под каждый брейкпоинт, если поведение можно решить ресайзом. + +### 3.2. Variants вместо копий +Состояния и вариации должны быть в **Variants**. + +Минимальный набор состояний (если применимо): +- `Default`, `Hover`, `Pressed/Active`, `Disabled`, `Focus`. + +Дополнительные состояния по необходимости: +- `Loading`, `Error`, `Success`, `Empty`. + +### 3.3. Требования к адаптивности компонентов +Компонент считается адаптивным, если: +- корректно меняет ширину при `Fill` (когда вставлен в растягиваемый контейнер); +- корректно меняет высоту при изменении контента (например, многострочный текст); +- не ломает паддинги и расстояния при ресайзе; +- корректно работает внутри разных контейнеров (list/grid, modal, sidebar). + +Обязательная проверка: +- вставьте компонент в контейнер разной ширины и измените ширину родителя; +- проверьте состояния и длину текста. + +### 3.4. Типовые требования по компонентам (примерно, без привязки к бренду) +- **Button**: фиксированная высота (например, 40/44/48 по дизайн-системе), ширина `Hug` или `Fill` по контексту, текст не должен вылезать (правила: перенос/обрезка задаются обоснованно). +- **Input**: высота фиксирована, поле `Fill`, лейбл и хелпер-текст — `Hug` с переносом. +- **Card**: контейнер `Fill`, текстовые блоки — `Hug` по высоте, изображение — обоснованный `Fill/Fit` с safe-area. + + + +## 4. Сетка / Layout Grid + +### 4.1. Зачем нужна сетка +Сетка задаёт предсказуемую структуру для: +- выравнивания и ритма; +- повторяемости решений; +- соответствия верстке. + +### 4.2. Базовая рекомендация по колонкам +| Device | Колонки | +|---------|---------| +| Mobile | 4 | +| Tablet | 8 | +| Desktop | 12 | + +Примечания: +- `Laptop` обычно использует 12 колонок (как Desktop), но может отличаться маржинами. +- Внутренний контейнер (max-width) допускается, если продукт предполагает «центрированный контент». + +### 4.3. Настройки (что должно быть задано) +Для каждого фрейма должны быть явно определены: +- `margin` (внешние поля); +- `gutter` (межколоночные расстояния); +- поведение сетки (`Stretch`/`Center`) — в зависимости от выбранной модели. + +Требование: +- сетка в Figma должна **соответствовать** принятой сетке в верстке (или быть согласована до начала дизайна). + +### 4.4. Пример логики перестроения с сеткой +- На Mobile: контент в 4 колонки, карточки занимают 4/4. +- На Tablet: 8 колонок, карточки 4/8 (2 колонки на ряд). +- На Desktop: 12 колонок, карточки 4/12 (3 колонки на ряд). + +--- + +## 5. Типографика + +### 5.1. Text Styles + Variables (обязательное правило) +Все текстовые слои в макете обязаны использовать **Text Styles**. + +Text Styles должны быть **семантическими** (а не «по экрану») и опираться на **типографические токены в Variables**. + +Минимальный набор (пример семантики): +- `H1`, `H2`, `H3` +- `Body / Regular`, `Body / Medium` +- `Caption` +- `Button` + +Требования: +- одинаковая семантика должна выглядеть согласованно во всех экранах; +- локальные «ручные» правки размеров/интервалов поверх стиля недопустимы (кроме редких исключений, зафиксированных правилом); +- разрешены только бесплатные шрифты; предпочтительно использовать **Google Fonts**; +- значения типографики (минимум `font-size` и `line-height`, при необходимости `letter-spacing`) — источник правды в **Variables**; +- адаптация типографики между брейкпоинтами делается через **Modes** в Variables, а не через дублирование текстовых стилей «под каждый брейкпоинт». + +### 5.2. Адаптация типографики между брейкпоинтами через Modes +Если типографика меняется между брейкпоинтами, это изменение фиксируется **через Modes** в коллекции Variables. + +Обязательная структура: +- есть коллекция Variables для типографики (например: `Typography`); +- в коллекции заведены Modes под брейкпоинты (например: `Mobile`, `Mobile Wide`, `Tablet`, `Laptop`, `Desktop` — в точности как принято в проекте); +- для каждого семантического стиля (`H1/H2/Body/...`) определены переменные минимум для: + - `font-size`; + - `line-height`; + - опционально: `letter-spacing` (редко и только обоснованно). + +Обязательное правило применения: +- Text Styles используют эти переменные как значения типографики; +- у каждого фрейма экрана выставлен корректный Mode (Mobile/Mobile Wide/Tablet/Laptop/Desktop), чтобы типографика внутри фрейма соответствовала брейкпоинту; +- любые отличия от токенов (если они вообще допускаются) должны быть подписаны: **что изменено**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. + +### 5.3. Многострочный текст: переносы и ограничения +Для ключевых текстовых блоков обязаны быть определены правила: +- переносится ли текст (wrap) или обрезается (truncate); +- сколько максимум строк допустимо в конкретном контексте (карточка/ячейка/таблица/заголовок/кнопка); +- что происходит при переполнении (например, `…`, перенос на следующую строку, увеличение высоты блока — что именно ожидается в UI). + +Минимальная проверка контента: +- короткий текст; +- нормальный (ожидаемый); +- длинный; +- «экстремальный» (очень длинный) — для выявления поломок; +- одна очень длинная строка без пробелов (проверка на разъезд/переполнение в узких контейнерах). + + + +## 6. Цвета и стили + +### 6.1. Цвета — только через Color Styles +Все цвета должны быть оформлены как **Color Styles**. + +Требование по именованию: +- семантика важнее оттенка. + +Пример семантических групп: +- `Primary / Secondary` +- `Text / Background / Border` +- `Success / Error / Warning` + +### 6.2. Дополнительные стили +Если в проекте используются: +- тени, +- блюр, +- обводки, +- радиусы, + +то они должны быть единообразны и по возможности вынесены в стили/токены (в рамках принятых процессов команды). + + + +## 7. Контент и состояния UI + +### 7.1. Контентные сценарии +Для каждого экрана/секции, где возможны вариации, должны быть проверены: +- короткий/длинный текст; +- пустые значения; +- максимальные значения (например, большие числа); +- локализация (если продукт многоязычный) — хотя бы проверка длины. + +### 7.2. Состояния UI (обязательный список) +В зависимости от компонента/экрана должны быть представлены состояния: +- `Default` +- `Hover` +- `Active/Pressed` +- `Disabled` +- `Focus` +- `Loading` +- `Empty` +- `Error` + +Требование: +- состояния должны быть реализованы либо в Variants компонентов, либо как отдельные фреймы/слои с явной маркировкой. + +### 7.3. Ошибки и валидация +Где есть ввод и формы, необходимо: +- указать правила отображения ошибок (текст, цвет, иконка, границы); +- учесть переполнение текста ошибки; +- показать состояние `Error` и `Focus` одновременно, если применимо. + + + +## 8. Изображения и медиа + +### 8.1. Обоснованный выбор Fill / Fit +- `Fill` (cover) используется, когда допустима обрезка. +- `Fit` (contain) используется, когда обрезка недопустима. + +### 8.2. Safe area для обрезки +Если используется `Fill`, у изображений должна быть предусмотрена **безопасная зона** (safe area): +- важные объекты (лицо, логотип, текст на фото) не должны попадать под обрезку при изменении пропорций. + +### 8.3. Разные соотношения сторон +Требование: +- если контент может приходить с разными ratio, дизайн обязан описать поведение: + - фиксируем ли высоту блока; + - разрешаем ли менять высоту по контенту; + - используем ли placeholder/фон. + + + +## 9. Навигация + +### 9.1. Паттерны по брейкпоинтам (базово) +- Desktop → горизонтальное меню +- Tablet → сокращённое меню (или гибрид) +- Mobile → бургер / bottom bar + +### 9.2. Требования к адаптивности навигации +- при уменьшении ширины не должно происходить «переполнения» пунктов меню; +- должны быть определены правила: + - что уходит в «ещё»/overflow; + - когда включается бургер; + - как ведут себя вторичные действия. + +### 9.3. Сложные случаи +Если навигация включает: +- табы, +- фильтры, +- хлебные крошки, + +то должно быть описано поведение на узких ширинах (скролл, перенос, сокращение, скрытие). + + + +## 10. Accessibility (A11y) + +### 10.1. Контраст +Требование: +- контраст текста и интерактивных элементов должен быть не ниже **WCAG AA** (если продуктом не задан иной стандарт). + +### 10.2. Размер клика (hit area) +Требование: +- минимальная интерактивная зона: **44×44 px**. + +### 10.3. Focus states и порядок +Обязательно: +- состояние `Focus` для интерактивных элементов; +- логичный `tab order` (особенно в формах и диалогах). + + + +## 11. Прототипирование + +### 11.1. Что обязательно прототипировать +- основные пользовательские флоу (критические пути); +- ключевые состояния (ошибка/пусто/загрузка) — если важны для сценария; +- диалоги, drawer, dropdown — если это влияет на понимание поведения. + +### 11.2. Переходы между брейкпоинтами +Если в продукте предполагается использование интерфейса в разных ширинах (веб), необходимо: +- зафиксировать, как ведёт себя интерфейс при переходе через пороги (например, при ресайзе окна). + +### 11.3. Проверка поведения при ресайзе +В прототипе или на странице `Responsive / Breakpoints` необходимо продемонстрировать: +- как перестраиваются блоки; +- что скрывается/появляется; +- где меняется навигационный паттерн. + + + +## 12. QA и проверка адаптивности + +### 12.1. Обязательный сценарий проверки +1) Ресайз фрейма вручную до min диапазона. +2) Ресайз до max диапазона. +3) Проверка промежуточных значений. +4) Проверка отдельных компонентов (в изоляции). +5) Проверка экстремальных контентных значений. + +### 12.2. Типовые ошибки (что искать) +- текст выходит за границы; +- кнопки/поля «схлопываются» ниже допустимого; +- пропадает сеточный ритм; +- карточки ломают высоту соседей непредсказуемо; +- элементы перекрывают друг друга при ресайзе; +- компоненты не тянутся, потому что внутри `Fixed` вместо `Fill/Hug`. + + + +## 13. Передача разработчику + +### 13.1. Dev Mode +Требование: +- Dev Mode включён и доступен; +- структуры слоёв достаточно для инспекта (без лишнего мусора и без превращения текста в вектор). + +### 13.2. Комментарии и пояснения +Должны быть комментарии/аннотации по: +- брейкпоинтам и порогам изменений; +- правилам скрытия/появления блоков; +- нестандартным случаям (например, «на 1024 фильтры переезжают в drawer»). + +### 13.3. Экспорт ассетов +Если требуется экспорт: +- указать форматы и размеры; +- убедиться, что иконки/иллюстрации подготовлены корректно (без лишних слоёв, с понятными именами). + + + +## 14. Запрещено + +- фиксированные ширины без причины (если элемент обязан тянуться); +- дубли компонентов под каждый экран вместо нормального ресайза; +- текст как вектор; +- «ручные» отступы вместо Auto Layout; +- отсутствие Auto Layout там, где есть паддинги/списки/повторяемые структуры. + + + +## 15. Минимальный стандарт качества (acceptance criteria) + +Макет считается адаптивным и готовым к разработке, если: +1. Корректно ресайзится во всём диапазоне каждого брейкпоинта. +2. Использует Auto Layout + корректные Resizing (Hug/Fill/Fixed) и Constraints. +3. Имеет якорные брейкпоинты, а дополнительные фреймы появляются только при структурных изменениях. +4. Компоненты оформлены как Components с Variants, состояния UI показаны. +5. Понятен разработчику без дополнительных «устных» пояснений: правила адаптивности описаны в файле. diff --git a/canons/figma/adaptive-layout-requirements.short.md b/canons/figma/adaptive-layout-requirements.short.md new file mode 100644 index 0000000..dec833f --- /dev/null +++ b/canons/figma/adaptive-layout-requirements.short.md @@ -0,0 +1,156 @@ +# Требования к адаптивному дизайну в Figma (Сжатая версия) + +> Примечание: в этом документе «обоснованно» означает: по каждому «выбору» (например: `Hug/Fill/Fixed`, wrap/truncate для текста, `Fill/Fit`) понятно **что выбрано**, **зачем** и **как это ведёт себя** на min/max диапазона и при длинном контенте. + +## 1. Структура файла Figma +Рекомендуемая структура: + +- **Cover / Overview** — описание проекта, цели, контакты, ссылки +- **Design / UI** — финальные экраны +- **Components** — повторяющиеся элементы и Variants +- **Styles / Tokens** — цвета, типографика, эффекты +- **Responsive / Breakpoints** — логика адаптивного поведения +- **Prototype** — интерактивные сценарии и флоу +- **Archive / Old** — устаревшие версии + +> Примечание: Страницы `Responsive / Breakpoints` и `Prototype` не дублируют дизайн-экраны, служат для объяснения поведения интерфейса и интерактивности. + + + +## 2. Брейкпоинты и адаптивность + +### 2.1. Якорные брейкпоинты +| Версия | Размер макета (Frame) | Диапазон (CSS px) | +|---------------|----------------|-------------------| +| Mobile | 375 px | 360 – 479 px | +| Mobile Wide | 560 px | 480 – 767 px | +| Tablet | 992 px | 768 – 1023 px | +| Laptop | 1280 px | 1024 – 1439 px | +| Desktop | 1640 px | 1440 – 1920 px | + + +- Каждый брейкпоинт — отдельный Frame в Figma. +- Количество брейкпоинтов **может корректироваться** (визуальная иерархия, контент, сетка, навигация). +- Все брейкпоинты должны быть **логически и визуально связаны**. + +### 2.2. Принцип «один фрейм — один диапазон» +- Один фрейм описывает **диапазон ширин**, а не отдельное устройство. +- Дополнительный фрейм — только при изменении сетки, навигации или структуры контента. + +### 2.3. Обязательное требование к ресайзу +- Макеты должны **корректно ресайзиться во всём диапазоне**, без дополнительных фреймов. +- Проверяется: + - изменение ширины фрейма вручную до min/max диапазона + - поведение сетки, карточек, текста, навигации + - отсутствие коллизий и переполнений + - сохранение визуальной иерархии + +> Макет некорректен, если работает только на базовой ширине. + +### 2.4. Реализация в Figma +- **Обязательно:** Auto Layout на всех контейнерах, обоснованный выбор `Hug / Fill / Fixed`, Constraints, min/max width для ключевых блоков. +- **Запрещено:** ручное позиционирование без Auto Layout, абсолютные размеры без необходимости, дубли фреймов для адаптивности. + + + +## 3. Компоненты +- Все повторяющиеся элементы — **Components**; использовать **Variants** вместо копий. +- Адаптивность компонентов: + - тянутся по ширине + - меняют высоту по контенту + - корректно ведут себя в разных контейнерах + + + +## 4. Сетка / Layout Grid +| Device | Колонки | +|---------|---------| +| Mobile | 4 | +| Tablet | 8 | +| Desktop | 12 | + +- Настройки: margin, gutter, column width +- Сетка должна соответствовать верстке + + + +## 5. Типографика +- Только через **Text Styles** (семантика: `H1 / H2 / Body / Caption / Button`) +- Только бесплатные шрифты (предпочтительно **Google Fonts**) +- Значения типографики (минимум размер и line-height) — через **Variables** +- Адаптация между брейкпоинтами — через **Modes** в Variables (Mobile/Mobile Wide/Tablet/Laptop/Desktop) +- Для ключевых текстов определены правила: wrap/truncate и max lines + + + +## 6. Цвета и стили +- **Color Styles** с семантическими названиями: + `Primary / Secondary`, `Text / Background / Border`, `Success / Error / Warning` + + + +## 7. Контент и состояния UI +- Текст: короткий / нормальный / длинный, проверка переполнения +- Состояния UI: Default, Hover, Active, Disabled, Focus, Loading, Empty, Error + + + +## 8. Изображения и медиа +- Использовать `Fill / Fit` обоснованно +- Safe area для обрезки +- Поддержка разных соотношений сторон +- Форматы и размеры соответствуют проекту + + + +## 9. Навигация +- Desktop → горизонтальное меню +- Tablet → сокращённое меню +- Mobile → бургер / bottom bar + + + +## 10. Accessibility (A11y) +- Контраст ≥ WCAG AA +- Минимальный размер клика: 44×44 px +- Focus states, логичный tab order + + + +## 11. Прототипирование +- Основные пользовательские флоу +- Переходы между брейкпоинтами +- Проверка поведения при ресайзе + + + +## 12. QA и проверка адаптивности +- Ресайз фрейма вручную до min/max диапазона +- Проверка компонентов отдельно +- Проверка экстремальных значений +- Макет готов, если ресайз работает корректно во всём диапазоне и нет коллизий + + + +## 13. Передача разработчику +- Dev Mode включён +- Комментарии с логикой адаптивности +- Описаны брейкпоинты, поведение блоков, скрытие/появление элементов + + + +## 14. Запрещено +- Фиксированные ширины без причины +- Дубли компонентов под каждый экран +- Текст как вектор +- Ручные отступы +- Отсутствие Auto Layout + + + +## 15. Минимальный стандарт качества +Макет считается адаптивным, если: +1. Корректно ресайзится во всём диапазоне +2. Использует Auto Layout + Constraints +3. Имеет брейкпоинты +4. Понятен разработчику без дополнительных объяснений diff --git a/canons/figma/index.md b/canons/figma/index.md new file mode 100644 index 0000000..638d9d5 --- /dev/null +++ b/canons/figma/index.md @@ -0,0 +1,30 @@ + +title: Figma Adaptive Standards +description: Карта стандартов подготовки адаптивных макетов в Figma для передачи в разработку + + +# Figma Adaptive Standards + +Figma Adaptive Standards — набор требований к подготовке адаптивных макетов в Figma. Документация фиксирует, как описывать брейкпоинты, проверять ресайз в диапазоне, настраивать Auto Layout и Constraints, оформлять компоненты, сетки, типографику, состояния интерфейса, A11y и передачу в разработку. + +Стандарты нужны, чтобы макет был не только визуальной картинкой на нескольких ширинах, а рабочей моделью поведения интерфейса. По документам должно быть понятно, как экран живёт между брейкпоинтами, какие элементы тянутся, какие перестраиваются, что происходит с длинным контентом и где дизайнерское решение требует отдельного пояснения. + +## Для кого + +- **Дизайнерам** — как чеклист качества адаптивного макета перед передачей в разработку. +- **Разработчикам** — как источник правил для проверки реализуемости макета и уточнения спорных мест. +- **Team Lead / DesignOps** — как единый стандарт приёмки дизайн-файлов и согласования процесса. + +## Разделы + +- [Сжатая версия](/adaptive-layout-requirements/short) — короткий набор требований для быстрого применения в проекте. +- [Полная версия](/adaptive-layout-requirements/full) — развёрнутое описание правил, терминов, проверок и типовых решений. +- [Чеклист приёмки](/adaptive-layout-requirements/checklist) — практический список проверок перед передачей макета в разработку. + +## Как читать + +Начните со сжатой версии, чтобы понять общий стандарт. Затем используйте полную версию как справочник по спорным вопросам: брейкпоинтам, ресайзу, Auto Layout, компонентам, сетке, типографике и состояниям UI. Перед передачей макета в разработку пройдите чеклист приёмки. + +## Главный принцип + +Адаптивный макет считается готовым не тогда, когда нарисованы несколько статичных фреймов, а когда понятна логика поведения интерфейса во всём диапазоне ширин: от минимального значения до максимального, с длинным контентом, разными состояниями и предсказуемой передачей в разработку. diff --git a/docs/figma-adaptive-standards/.vitepress/config.ts b/docs/figma-adaptive-standards/.vitepress/config.ts new file mode 100644 index 0000000..55477f3 --- /dev/null +++ b/docs/figma-adaptive-standards/.vitepress/config.ts @@ -0,0 +1,19 @@ +import { defineConfig } from 'vitepress'; +import llmstxt from 'vitepress-plugin-llms'; +import { sidebar, site } from '../docs.config'; + +export default defineConfig({ + title: site.title, + description: site.description, + base: site.base, + outDir: site.outDir, + srcDir: 'content', + cleanUrls: true, + vite: { + plugins: [llmstxt()], + }, + themeConfig: { + sidebar, + socialLinks: [], + }, +}); diff --git a/docs/figma-adaptive-standards/docs.config.ts b/docs/figma-adaptive-standards/docs.config.ts new file mode 100644 index 0000000..5eacdd2 --- /dev/null +++ b/docs/figma-adaptive-standards/docs.config.ts @@ -0,0 +1,33 @@ +export const site = { + title: 'Figma Adaptive Standards', + description: 'Стандарты подготовки адаптивных макетов в Figma', + base: '/figma-adaptive-standards/', + outDir: '../../public/figma-adaptive-standards', +}; + +/** + * Карта монтирования исходных канонов в VitePress-документацию. + * + * `source` указывает на markdown-файл внутри `canons/`. + * `target` задаёт путь, по которому этот файл попадёт в `docs/figma-adaptive-standards/content/` + * и станет страницей итоговой документации. + */ +export const mounts = [ + { target: 'index.md', source: 'figma/index.md' }, + { target: 'overview.md', source: 'figma/index.md' }, + { target: 'adaptive-layout-requirements/short.md', source: 'figma/adaptive-layout-requirements.short.md' }, + { target: 'adaptive-layout-requirements/full.md', source: 'figma/adaptive-layout-requirements.full.md' }, + { target: 'adaptive-layout-requirements/checklist.md', source: 'figma/adaptive-layout-requirements.checklist.md' }, +]; + +export const sidebar = [ + { + text: 'Стандарты', + items: [ + { text: 'Обзор', link: '/overview' }, + { text: 'Сжатая версия', link: '/adaptive-layout-requirements/short' }, + { text: 'Полная версия', link: '/adaptive-layout-requirements/full' }, + { text: 'Чеклист приёмки', link: '/adaptive-layout-requirements/checklist' }, + ], + }, +]; diff --git a/package.json b/package.json index 995c42c..1fb318d 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,8 @@ "build": "npm run site:generate && tsc -b && vite build", "docs:prepare:slm-design": "tsx scripts/docs/prepare.ts slm-design", "docs:build:slm-design": "npm run docs:prepare:slm-design && vitepress build docs/slm-design", + "docs:prepare:figma-adaptive-standards": "tsx scripts/docs/prepare.ts figma-adaptive-standards", + "docs:build:figma-adaptive-standards": "npm run docs:prepare:figma-adaptive-standards && vitepress build docs/figma-adaptive-standards", "site:generate": "tsx scripts/site/generate-artifacts.ts", "lint": "eslint .", "preview": "vite preview" diff --git a/src/config/docs.config.ts b/src/config/docs.config.ts index d22d292..06d02a2 100644 --- a/src/config/docs.config.ts +++ b/src/config/docs.config.ts @@ -57,7 +57,8 @@ export const docs: DocCard[] = [ label: 'Макеты', mark: 'FG', description: 'Стандарты и требования к подготовке адаптивных макетов в Figma: брейкпоинты, ресайз в диапазоне, Auto Layout/Constraints, компоненты, сетка, типографика, состояния UI, A11y и передача в разработку.', - status: 'Скоро', + href: '/figma-adaptive-standards/', + status: 'Доступно', accent: 'pink', links: [ { label: 'llms.txt', href: '/figma-adaptive-standards/llms.txt' },