SHiNE-server/Dev_Docs/Figma/TRANSFER_UI_SCREENS.md

Перенос экранов 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-правки.