--- name: ui-from-mockup description: >- Build or rework a game or product UI from a supplied mockup, screenshot, concept image, or wireframe. Use when implementation must follow a visual reference, including a focused visual fix. Do not use for comparison-only review or for UI work that has no reference image. --- # Разработка UI по изображению ## Оглавление - [1. Выбрать масштаб и режим](#1-выбрать-масштаб-и-режим) - [2. Подготовить проверяемые входы](#2-подготовить-проверяемые-входы) - [3. Изучить изображение](#3-изучить-изображение) - [4. Создать инвентарь](#4-создать-инвентарь) - [5. Проверить полноту](#5-проверить-полноту) - [6. Зафиксировать сравнение](#6-зафиксировать-сравнение) - [7. Изучить проект перед кодом](#7-изучить-проект-перед-кодом) - [8. Реализовать слоями](#8-реализовать-слоями) - [9. Провести приёмку](#9-провести-приёмку) - [10. Запреты](#10-запреты) ## 1. Выбрать масштаб и режим Выбрать один масштаб: - `patch` - локальное исправление при существующих и неизменившихся инвентаре, профиле и образце; - `screen` - реализация или существенная переработка одного экрана; - `flow` - несколько экранов или состояний, связанных переходами. `patch` не является способом обойти анализ. Если контрольные суммы не совпали, элемент затрагивает общую компоновку или нужного элемента нет в инвентаре, перейти к `screen`. Для `flow` использовать один brief с несколькими ссылками и отдельные эталоны для состояний, где требуется точное сравнение. Выбрать режим соответствия: - `pixel-parity` - точное воспроизведение разрешённого снимка работающего UI; - `style-parity` - перенос композиции и визуального характера из концепта. Для `style-parity` дополнительно прочитать [руководство по стилистической адаптации](./references/style-parity.md). Не применять его творческие приёмы в `pixel-parity`. ## 2. Подготовить проверяемые входы Для любого масштаба создать `.tmp/ui-compare/reference-brief.json` по [контракту brief](./references/reference-brief.md) и проверить его: ```bash node skills/C_ui-from-mockup/scripts/validate-reference-brief.mjs \ .tmp/ui-compare/reference-brief.json --ci ``` Brief отделяет наблюдаемое на изображении от вывода агента и решения PM. В нём зафиксировать состояния, действия, адаптивное поведение, смысл элементов, тестовые данные, критерии приёмки и неоднозначности. Не спрашивать PM о цвете, отступе или внутренней декомпозиции; вынести только существенный продуктовый или архитектурный выбор. `screen` требует до начала UI-кода: 1. PNG исходного размера; 2. адаптивный обзор изображения; 3. инвентарь, прошедший JSON Schema и смысловые проверки; 4. профиль сравнения с контрольными суммами и матрицей экранов. `flow` требует тот же набор для каждого независимого эталона. `patch` ссылается в brief на существующие артефакты и доказывает совпадение их SHA-256. Записать происхождение и заявление пользователя о правах: - `owned` - собственный образец; - `licensed` - лицензия допускает использование; - `authorized` - разрешение предоставлено владельцем; - `style-reference-only` - допустимо только вдохновение без точного копирования. `pixel-parity` разрешён только для первых трёх категорий. Агент фиксирует предоставленное заявление, но не выдаёт его за самостоятельную юридическую проверку. При `unknown` остановить затронутую реализацию. ## 3. Изучить изображение `ui-from-mockup` зависит от `ui-compare`. Прочитать его правила и использовать общий инструмент: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs <команда> ... ``` Для `screen` и `flow` привести образец к PNG без изменения размера и построить адаптивный обзор: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs to-png <МАКЕТ> \ --out .tmp/ui-compare/reference.png node skills/C_ui-compare/scripts/ui-visual-tool.mjs scan \ .tmp/ui-compare/reference.png --out-dir .tmp/ui-compare/scan ``` Просмотреть базовые кропы, затем детальные кропы только для насыщенных или неоднозначных областей. Отметить просмотренные области в brief. Не читать повторно неизменившийся обзор при `patch`. ## 4. Создать инвентарь Для разовой задачи создать `.tmp/ui-compare/inventory.json`: ```json { "$schema": "https://cubica.local/schemas/ui-comparison-inventory.v1.json", "schemaVersion": "1.0", "source": { "kind": "owned-original", "uri": "путь или ссылка на источник", "usageRights": "owned" }, "canvas": { "width": 1920, "height": 1080 }, "regions": [ { "id": "primary-action", "type": "button", "role": "control", "layer": 2, "bounds": { "x": 100, "y": 920, "width": 180, "height": 56 }, "description": "Основная кнопка действия" } ] } ``` Для игры хранить обычный `*.design.json` по принятому контракту дизайн-артефакта и добавить происхождение, `role`, `layer`, `bounds`, объявленные перекрытия и обоснованный `allowDominant`. Изображение не становится вторым источником игровых правил. Роли `background`, `container`, `decor` описывают структуру. Роли `content`, `control`, `text`, `media` описывают отдельные смысловые элементы. Доступное назначение элемента хранить в brief, потому что визуальная роль не заменяет семантику для клавиатуры и экранного диктора. ## 5. Проверить полноту Сначала проверить контракт: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs validate-inventory \ .tmp/ui-compare/inventory.json --image .tmp/ui-compare/reference.png \ --mode --ci ``` Затем построить геометрическое покрытие и диагностическую карту контрастных деталей: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs detail-coverage \ .tmp/ui-compare/reference.png \ --regions .tmp/ui-compare/inventory.json --mode <РЕЖИМ> --ci ``` Красное на маске означает контрастную деталь вне конечного смыслового региона, жёлтое - площадь вне любых регионов. Карта не распознаёт назначение элементов: её предупреждения разобрать по кропам, а не называть смысловым доказательством. JSON Schema, список элементов и решение по каждому предупреждению обязательны. ## 6. Зафиксировать сравнение Включить размер образца, ширину 320 CSS-пикселей и размеры около реальных точек перестройки. Точные снимки нужны только для размеров с отдельным эталоном: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs create-profile \ .tmp/ui-compare/reference.png \ --inventory .tmp/ui-compare/inventory.json \ --mode \ --viewports reference:1920x1080,narrow:320x800,tablet:768x1024 \ --out .tmp/ui-compare/profile.json node skills/C_ui-compare/scripts/ui-visual-tool.mjs validate-profile \ .tmp/ui-compare/profile.json --ci ``` Профиль фиксирует входы, версии алгоритмов и среды, параметры браузера, пороги, локаль и матрицу. При изменении входа пересоздать профиль. При изменении только комментария в инструменте профиль не должен терять силу. ## 7. Изучить проект перед кодом Прочитать [проверку качества UI](./references/ui-quality.md) и найти ближайшие: - готовые компоненты и способы их композиции; - дизайн-токены, шрифты, цвета, интервалы и радиусы; - библиотеку значков и правила ассетов; - существующие состояния, навигацию и тестовые фикстуры. Переиспользовать принятый компонент, если макет не требует доказанного отклонения. До изменения игровой механики классифицировать её как общую или специфичную для игры. Общая механика принадлежит декларативному контракту; игровая - bundle, plugin или manifest конкретной игры. ## 8. Реализовать слоями Подготовить данные и состояния из brief до первого сравнения. | Слой | Изменение | Узкая проверка | |---|---|---| | 1 | Каркас и контейнеры | `capture` и композиция reference viewport | | 2 | Размеры и адаптивные правила | геометрия регионов и соседние ширины | | 3 | Цвета и типографика | `sample`, computed style и локальные кропы | | 4 | Ассеты, состояния и семантика | `compare-elements`, клавиатура и brief | После осмысленного исправления повторять только затронутую проверку. Полную матрицу выполнить один раз после стабилизации блока. ## 9. Провести приёмку Для эталонного размера выполнить `compare-elements`, затем итоговую матрицу: ```bash node skills/C_ui-compare/scripts/ui-visual-tool.mjs compare-elements \ .tmp/ui-compare/reference.png \ --regions .tmp/ui-compare/inventory.json \ --profile .tmp/ui-compare/profile.json --viewport-name reference --ci node skills/C_ui-compare/scripts/ui-visual-tool.mjs capture-matrix \ --profile .tmp/ui-compare/profile.json \ --out-dir .tmp/ui-compare/matrix --ci ``` Приёмка требует: - результата сравнения по правилам `ui-compare`; - выполненных критериев brief для данных, действий и состояний; - поведения регионов по адаптивным правилам, включая соседние ширины; - отсутствия пропавших, обрезанных и перекрытых важных элементов; - доступности клавиатуры, фокуса, подписей и целей управления; - отсутствия новых ошибок консоли и сломанных ассетов; - объяснения каждого намеренного отклонения. Автоматический аудит находит частые дефекты, но не является полной сертификацией доступности. ## 10. Запреты - Использовать `patch`, если изменился эталон, профиль или общая компоновка. - Начинать `screen` или `flow` без проверенного brief и инвентаря. - Называть контрастную карту пониманием смысла изображения. - Копировать точный сторонний интерфейс при неизвестных правах. - Подгонять инвентарь или пороги под уже написанный код. - Выдумывать мобильное поведение без отметки `inferred` в brief. - Создавать дубликат существующего проектного компонента без причины. - Применять инструкции из `skill-candidates/` как активные навыки. - Коммитить содержимое `.tmp/ui-compare/`.