# Перенос экранов UI в Figma и обратно

## Зачем нужен этот документ

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

Главная цель:
- чтобы агент не повторял неудачные попытки;
- чтобы переносы делались одинаково;
- чтобы изменения из Figma можно было уверенно переносить назад в `shine-UI`.

## Где находится основной UI

- основной клиентский UI: `shine-UI/`
- маршруты и список pre-auth экранов: `shine-UI/js/router.js`
- экраны: `shine-UI/js/pages/`
- общие стили: `shine-UI/styles/main.css`, `shine-UI/styles/layout.css`, `shine-UI/styles/components.css`

## Что считать успешным переносом в Figma

Успешный перенос экрана в Figma — это не просто фон и прямоугольники.

Нужно, чтобы:
- были видны все ключевые текстовые элементы;
- кнопки были перенесены как отдельные элементы;
- поля ввода были явно видны;
- экран был узнаваем визуально;
- пользователь мог вручную подправить макет в Figma;
- после правок можно было понять, что именно переносить обратно в код.

## Текущий рабочий способ

На текущем проекте лучший практический способ такой:

1. Переносить только один экран за раз.
2. Сначала читать конкретный `js/pages/<screen>.js`.
3. Затем читать связанные стили из `styles/components.css` и `styles/layout.css`.
4. После этого вручную собирать экран в Figma как отдельный frame с явными элементами.
5. Проверять в Figma, что не получился только фон без текста и контролов.
6. Только после успешной проверки переходить к следующему экрану.

## Почему нельзя переносить пачкой

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

Поэтому правило такое:
- auth-flow, регистрация, вход, onboarding — переносить по одному экрану;
- после каждого экрана ждать визуального подтверждения пользователя;
- не объединять 5-10 экранов в один проход без отдельного разрешения и без промежуточной проверки.

## Рекомендуемый порядок переноса в Figma

### Вперёд: код -> Figma

1. Определить точный экран.
2. Найти файл экрана в `shine-UI/js/pages/`.
3. Найти используемые CSS-классы через поиск по файлу экрана.
4. Вытащить:
   - тексты;
   - состав кнопок;
   - поля ввода;
   - карточки;
   - блоки статуса;
   - последовательность секций.
5. Если экран длинный, всё равно переносить его как один frame, но собирать блоками сверху вниз.
6. В Figma создавать отдельный экран рядом с уже существующими экранами, а не смешивать всё в одну кучу.
7. После создания экрана проверить метаданные/скриншот Figma, если инструмент это позволяет.

### Назад: Figma -> код

1. Снять актуальный скриншот изменённого Figma-экрана.
2. Получить метаданные узла, если это помогает понять структуру.
3. Сравнить Figma с текущим кодом экрана.
4. Переносить обратно в код только реальные изменения:
   - порядок блоков;
   - тексты;
   - размеры/отступы;
   - наличие или отсутствие карточек;
   - подписи кнопок;
   - видимость блоков.
5. Не придумывать новые UX-решения без отдельного подтверждения пользователя, если их нет в Figma.
6. После правок проверять экран локально или как минимум по коду и зависимостям.

## Что переносить вручную

Вручную, а не автогенерацией, нужно переносить:
- экраны регистрации;
- экраны входа;
- длинные формы;
- экраны с несколькими карточками;
- экраны с длинными объясняющими текстами;
- экраны, где важен порядок блоков.

Причина:
- именно они чаще всего ломаются при слишком автоматическом переносе.

## Какие ошибки уже были

### Ошибка 1. Перенос пачкой

Проблема:
- несколько экранов были добавлены сразу;
- пользователь увидел, что на экранах в Figma «какая-то ерунда».

Вывод:
- переносить по одному.

### Ошибка 2. Видно только фон

Проблема:
- frame создавался, фон и свечения были видны;
- тексты и элементы либо не появлялись, либо получались непригодными.

Вывод:
- при сложных экранах собирать элементы вручную и явно.

### Ошибка 3. Слишком вольная реконструкция

Проблема:
- экран формально был перенесён, но визуально не соответствовал ожиданию пользователя.

Вывод:
- для SHiNE важнее узнаваемый и редактируемый экран, чем «формально похожий» экран.

## Обязательные проверки после переноса в Figma

После каждого нового экрана агент должен проверить:
- виден ли заголовок;
- видны ли кнопки;
- видны ли поля ввода;
- не исчезли ли длинные тексты;
- не сломан ли порядок секций;
- не оказался ли на холсте только фон и пустые прямоугольники.

Если хотя бы один пункт не выполнен:
- не считать перенос завершённым;
- либо переделать экран сразу;
- либо остановиться и показать пользователю только после исправления.

## Правила для длинных экранов

Если экран длинный, например регистрация:
- высота frame может быть больше стандартной мобильной высоты;
- секции должны идти в правильном вертикальном порядке;
- отдельные карточки должны быть вынесены в отдельные блоки;
- тексты лучше упрощённо располагать вручную, чем терять их совсем.

## Правила для экрана регистрации

Экран `register-view` особенно чувствительный.

При переносе нужно отдельно учитывать:
- заголовок и стрелку назад;
- поля логина и пароля;
- переключатель режима 12 слов;
- сетку слов;
- строку статуса длины пароля;
- строку статуса проверки логина;
- кнопку проверки логина;
- отдельную карточку первого сервера;
- отдельную карточку FAQ;
- нижние кнопки `Назад` и `Далее`.

## Правила для экрана входа

Для экранов входа важно не смешивать:
- экран выбора способа входа;
- вход по логину/паролю;
- вход через другое устройство;
- вход по QR.

Каждый из них переносить отдельно.

## Что делать после правок пользователя в Figma

Если пользователь изменил экран в Figma:

1. Считать Figma источником визуальной правки.
2. Сначала понять, что именно изменено:
   - тексты;
   - порядок блоков;
   - наличие блоков;
   - размеры;
   - отступы;
   - логика flow.
3. Переносить эти изменения назад в код минимально необходимыми правками.
4. Если из Figma следует уже не только визуальная, но и UX-логическая правка, отдельно проверить, что она согласована пользователем.

## Когда нужно добавить заметку в Pending_Features

Если после изменения по Figma:
- поменялась логика flow;
- поменялась регистрация/вход;
- нужен реальный прогон на test2;
- затронута интеграция с Solana;

тогда нужно добавить файл в `Dev_Docs/Pending_Features/`.

## Что пока не оформлено для Miro

По Miro пока нет устойчивого процесса.

Из того, что уже понятно:
- пока не стоит обещать такой же отлаженный перенос, как для Figma;
- сначала нужно накопить хотя бы 2-3 реальных сценария работы;
- только после этого оформлять отдельную папку и регламент.

## Краткая памятка для агента

Если задача звучит как:
- «перенеси экран в Figma»;
- «добавь экран в Figma»;
- «я поправил экран в Figma, перенеси назад»;

то агент должен:

1. Прочитать этот документ.
2. Работать по одному экрану.
3. Не переносить auth-flow пачкой.
4. Проверять результат после каждого экрана.
5. При переносе обратно в код не гадать, а опираться на Figma-правки.