Ui Source Mapping

---
name: ui-source-mapping
description: "Обратное сопоставление: скриншот работающего UI → точное место в СУЩЕСТВУЮЩЕМ коде. Определение «существующий проект vs новый», извлечение якорей со скриншота (видимый текст, ключи i18n, иконки, структура), grep-стратегия поиска компонента, трассировка маршрута (Next.js App/Pages Router, React Router), вычисление конкретного контрола и его обработчика, разбор логики (состояние/стор, data-fetch, API), вывод как карта file:line + делегирование правки. Use когда по скриншоту надо найти и понять уже существующий UI, а не сгенерировать новый."
version: 1.0.0
---

# Навык: UI → Source Mapping (скриншот → существующий код)

Цель — по скриншоту работающего интерфейса **найти его в реальной кодовой базе** и объяснить, как он устроен: компонент, маршрут, контрол, логика — с точностью до `file:line`. Ничего не генерируешь и не правишь; отдаёшь карту и делегируешь правку. Это обратная задача к `screenshot-to-code`. Работает в связке с `frontend-architecture`, `react`/`nextjs`, `data-fetching`/`state-management`, `i18n`.

## 0. Существующий проект или новый
Сначала реши, твой ли это случай:
- Есть кодовая база (`package.json`, `src/`, git) и якоря со скриншота грепаются по ней → **существующий**, работай на привязку.
- Greenfield / скриншот как макет для нового UI → это `screenshot-to-code` (генерация), перенаправь.
- Сомнение → грепни якоря по репозиторию; совпадения решают. Не выдумывай файлы.

## 1. Якоря со скриншота
Открой изображение (инструмент Read показывает картинку) и вытащи то, по чему можно искать в коде (от уникального к общему):
- **Видимый текст** — заголовки, лейблы кнопок, плейсхолдеры, пункты меню, тосты/ошибки, бейджи. Самый сильный ключ.
- **Иконки** — по имени из набора (lucide/heroicons/…), `aria-label`.
- **Структура** — шапка/сайдбар/контент/модалка, тип компонента (таблица/карточки/табы/форма/степпер).
- **Контекст маршрута** — активный пункт навигации, крошки, заголовок вкладки, видимый URL.
- **Состояние** — открытый таб/модалка/шаг, выделение, disabled/active — чтобы не спутать с похожим экраном.

## 2. i18n: текст на экране ≠ текст в коде
В мультиязычном проекте на экране видно **значение перевода**, а в JSX стоит **ключ** (`t('cart.checkout')`). Стратегия: (1) грепни видимую строку по файлам локали (`locales/**`, `*.json`/`*.po`) → получи ключ; (2) грепни ключ по компонентам → получи место. В одноязычном — текст обычно литералом, грепается напрямую. См. `i18n`.

## 3. Grep-стратегия (находим компонент)
- Ищи `rg` от **самой редкой** строки к частой: точная фраза → её часть → ключ перевода → имя иконки.
- Чисти шум: игнорируй `node_modules`/сборку; сначала `src/`.
- Много совпадений — сузь по соседним якорям (текст + иконка + тип блока в одном файле).
- Ноль совпадений — проверь склейку строк (`'Add ' + noun`), формат-шаблоны, вынесенные константы, текст из API/CMS; тогда ищи по стабильному фрагменту или `data-testid`/`aria-label`.

## 4. Маршрут (где открыт экран)
Свяжи компонент с URL по конвенциям:
- **Next.js App Router** — `app/**/page.tsx`, вложенные сегменты, динамические `[param]`, группы `(group)`, `layout.tsx` для общего каркаса.
- **Next.js Pages Router** — `pages/**` (файловый роутинг), `_app`/`_document`.
- **React Router** — `<Route path=…>` / `createBrowserRouter`, вложенные `Outlet`, `index`-роуты.

Иди в обе стороны: от компонента → кто его импортирует/рендерит → до `page`/`Route`; и от активного пункта навигации → его `href`/`to` → до целевого маршрута.

## 5. Контрол (с чем работает пользователь)
Среди найденного вычисли **конкретный** элемент: по тексту/`aria-label`/иконке/позиции относительно соседей. Найди его обработчик — `onClick`/`onSubmit`/`onChange` — и куда он ведёт (локальный хендлер, экшен стора, мутация). Несколько похожих кнопок — раздели по различающему признаку (текст, `variant`, ближайший заголовок).

## 6. Логика (что за контролом)
От обработчика вглубь:
- **Состояние/стор** — `useState`/`useReducer`, Zustand/Redux-срез, контекст (см. `state-management`).
- **Данные** — загрузка/мутация: React Query/SWR/`fetch`/`openapi-fetch`, какой эндпоинт дёргается (см. `data-fetching`).
- **Бэкенд** — при необходимости дойди до роута/контроллера, обслуживающего вызов.

Формулируй как первопричину поведения, а не ближайший JSX.

## 7. Вывод — карта «скриншот → исходники»
Отдай структурировано, каждый пункт с `file:line` + короткий фрагмент:
- **Экран:** компонент — `file:line`.
- **Маршрут:** URL/путь — где объявлен.
- **Контрол:** элемент + обработчик — `file:line`.
- **Логика:** обработчик → состояние/стор → data-fetch → API.
- **Правка:** что менять в существующем коде (без новых файлов/компонентов) и какому субагенту (`frontend`/`backend`) делегировать.

## 8. Границы
Только чтение — не правишь и не создаёшь. Работаешь с тем, что уже есть: цель — переиспользовать существующие компонент/обработчик/стиль. Неоднозначность — список кандидатов с различием, критичное — уточнить. Если это генерация нового UI — верни задачу в `screenshot-to-code`.