houseplan-card/docs/reviews/SPEC-REVIEW-179-r1.md

Ревью ТЗ — issue #179, цикл r1

• Issue: https://github.com/Matysh/houseplan-card/issues/179
• ТЗ: docs/specs/179-device-icons-redesign.md (коммит 517a710, ветка issue/179-device-icons-redesign)
• Трек: обычный (аналитика явно исключила small/trivial)
• Вердикт: жёлтый · цикл r1/4 · High: 0 · Medium: 5 (все в скоупе задачи) · Low: 2

Скоуп ревью

Проверялось только ТЗ как артефакт этапа S4-spec-review: обязательные разделы §7.1 PROCESS.md, однозначность и доказуемость AC1…AC14, соответствие docs/SCOPE.md (J1/J2/J7), docs/USER-GUIDE.ru.md, docs/CONFIG-COMPATIBILITY.md, docs/TOUCH-SUPPORT.md, а также фактическое соответствие ТЗ нормативному источнику — архиву дизайнера, приложенному к issue #179. Продуктовый код не существует (issue не дошёл до S5-ready), поэтому код не проверялся.

Как проверялось

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком.
2. Прочитано тело issue #179 и все три комментария (gh issue view 179 --json ...).
3. Прочитан файл ТЗ целиком (534 строки).
4. Архив дизайнера скачан и распакован (curl по ссылке из тела issue, sha256sum совпал с указанным в ТЗ 63670C73...), чтобы проверить не только внутреннюю согласованность ТЗ, но и его фактическое соответствие нормативному источнику — это единственный способ отличить решение владельца от догадки, выданной за факт:
   • SPECIFICATION.md, ACTIVE_ANIMATION_SPEC.md, DEVELOPER_HANDOFF.md, README.md, PACKAGE_ANNOTATION.txt, manifest.json — построчно;
   • геометрия и цвета — вычислены из реальных SVG (viewBox, <rect>, <path> координаты circle-shell, fill/stroke, feColorMatrix);
   • тайминги анимаций — вычислены из @keyframes/animation в Animated/Light/*.svg (текстовые документы архива тайминги короткого события и alert не дают, только качественное описание).
5. Сверено с текущей реализацией: src/device-pulse.ts, src/device-presentation.ts, src/styles.ts, src/types.ts, src/houseplan-card.ts — чтобы отличить утверждения ТЗ о «текущем поведении» (раздел «До реализации») от факта, и проверить, действительно ли новая раскладка цветов континуальной пульсации — новшество.
6. Прочитаны релевантные фрагменты docs/USER-GUIDE.ru.md (терминология состояний, приоритет статусов, пульсация, «Всегда статичный значок», LQI комнаты) и docs/CONFIG-COMPATIBILITY.md, docs/TOUCH-SUPPORT.md целиком.
7. Код не запускался, гейты не прогонялись — на этапе ревью ТЗ кода нет, раздел «Гейты» PROCESS.md §8 к этому циклу неприменим.

Находки

M1 — цвет внешней тени искажён относительно нормативного источника

Файл: docs/specs/179-device-icons-redesign.md:122-123

ТЗ утверждает для light-shell на референсе 56 px: 0 1px 2px rgb(0 0 0 / 12%) и 0 4px 8px -1.07px rgb(0 0 0 / 18%) — чистый чёрный.

Нормативный источник (SPECIFICATION.md, таблица §8) даёт другой цвет: 0 1px 2px 0 rgb(37 40 45 / 12%) и 0 4px 8px -1.07px rgb(37 40 45 / 18%). Это подтверждается самим SVG: feColorMatrix в Light/Icon Default.svg задаёт 0.145098 / 0.156863 / 0.176471 — это ровно 37/255, 40/255, 45/255, то есть тёплый тёмно-серый #25282D, а не #000000.

По порядку приоритета самого ТЗ (§3: решения владельца → текстовые документы архива → SVG-примеры → текущая реализация) текстовый документ и SVG совпадают между собой и расходятся с ТЗ; решения владельца по этому пункту нет. Это не разночтение источников, а фактическая ошибка транскрибирования в самом ТЗ.

Почему это важно: AC1 обещает golden-эталон 32/56/96 px по геометрии и токенам пакета. Реализация по тексту ТЗ буквально даст на глаз более резкую, холодную тень, чем в дизайне, и это will пройти собственный (неверный) golden, проверяющий не то, что задумано.

Требуется: заменить rgb(0 0 0 / …) на rgb(37 40 45 / …) в §7.1 (обе тени, 56 px референс; проверить также, что при масштабировании на 32/96 px в реализации используется тот же цвет).

M2 — цвет continuous-пульсации для reason presence не определён

Файл: docs/specs/179-device-icons-redesign.md:222-230 (§10.1), :129-144 (§7.2)

Пакет содержит три статических и три анимированных варианта Continuous Working: Default (обводка #0C82F0), Yellow (#F0A00C), Green (#1DC21D). SPECIFICATION.md §4 перечисляет источники непрерывной работы: «свет, вентилятор, климат, уборка, присутствие» — но ни один текстовый документ архива (SPECIFICATION.md, ACTIVE_ANIMATION_SPEC.md, DEVELOPER_HANDOFF.md) не говорит, какому из трёх цветов соответствует какая причина. Green нигде не привязан к семантике — ни в архиве, ни в ТЗ.

Это не абстрактная тонкость: в текущей реализации resolveDevicePulse (src/device-pulse.ts:93-103) уже различает три причины continuous-пульсации — presence, transition, running — но все три сегодня рисуются одним переданным цветом, без различия по причине. Пакет впервые вводит три разных цветовых варианта того же мотива, а ТЗ §7.2/§10.1 говорит только «цвет соответствует resolved ordinary activity», не решая: (а) вводится ли новое различение по reason (presence → зелёный, как логично предположить по тексту пакета) или (b) Green-ассет в этой итерации не используется вовсе.

AC8 требует, чтобы «цвета соответствовали §10» — при текущем тексте §10 это непроверяемо для presence-пульсации, потому что нормативного значения нет ни в одном документе.

Требуется: явное решение (не владельца — это техническое/дизайн-решение, которое ТЗ вправе принять само, см. PROCESS.md §7.1 "всё, чего пользователь не наблюдает, агенты решают сами"; здесь пользователь наблюдает результат, но выбор между двумя понятными вариантами не требует владельца) — либо зафиксировать маппинг presence → Green, либо явно исключить Green из поставки с пометкой «принято предположительно» в §20.

M3 — easing для Short и Alert не зафиксирован

Файл: docs/specs/179-device-icons-redesign.md:232-246 (§10.2, §10.3)

§10.1 (Continuous) корректно и проверяемо квотирует cubic-bezier(.45,.05,.55,.95) — совпадает с ACTIVE_ANIMATION_SPEC.md и с working-ring/working-core-blue в Animated/Light/Continuous Working Default Animated.svg. §10.2 (Short) и §10.3 (Alert) дают duration, delay, scale, stroke, цикл — но не easing. В реальных SVG (Animated/Light/Short Activity Animated.svg, Animated/Light/Alert Animated.svg) обе анимации используют cubic-bezier(.22,.61,.36,1) — другую кривую, чем Continuous. ACTIVE_ANIMATION_SPEC.md этот параметр текстом тоже не называет, только качественно («цикл должен быть плавным»), то есть источник факта — только SVG-пример (третий приоритет по ТЗ), и раз он существует и однозначен, ТЗ должен был его перенести.

AC8 обещает «timings ... и colors соответствуют §10» — без easing реализация по умолчанию получит линейное или произвольное ускорение, что даст другое ощущение движения и не пройдёт визуальную приёмку по духу задачи ("читаемое глазами" состояние).

Требуется: добавить easing: cubic-bezier(.22,.61,.36,1) в §10.2 и §10.3.

M4 — стоимость и выбор backdrop-blur для Dark не решены

Файл: docs/specs/179-device-icons-redesign.md:125-127 (§7.1), §17 (риски), AC13

manifest.json прямо объявляет "backdropBlurPx": 20 для темы Dark, и Dark/Icon Default.svg реально содержит foreignObject с backdrop-filter:blur(20px) — а не просто SVG-тень. Пакет отдельно поставляет Dark/Icon Default No Blur.svg, который побайтно совпадает с Icon Default.svg за вычетом именно этого слоя (проверено diff'ом), и, в отличие от Light-алиаса, не помечен в manifest.json как deprecated/aliasOf — то есть это не забытый дубликат, а отдельный, специально сохранённый fallback.

ТЗ §7.1 ограничивается «Dark использует неизменённую dark-ревизию пакета… эталонные эффекты» — не решая, войдёт ли backdrop-filter: blur(20px) на каждый маркер в продакшен, или используется No-Blur вариант. Это не мелочь: backdrop-filter — дорогая по композитингу операция; docs/SCOPE.md называет 20–200 устройств на план и киоск-планшет как основную View-поверхность для двух из трёх персон (docs/TOUCH-SUPPORT.md: View/kiosk — блокирующие). В src/ сегодня backdrop-filter не применяется ни к одному маркеру (только к editor-tray, src/editor-secondary.styles.ts), так что это действительно новая для маркеров нагрузка, а не продолжение существующей. AC13 («нет per-frame JS, ResizeObserver…») не упоминает composite-cost blur-слоёв, и §17 «Риски» этот риск не называет вовсе.

Требуется: явное решение — либо применять blur (тогда назвать это в §17 и покрыть производительность в AC13/perf-профиле), либо взять готовый No-Blur Dark-ассет как основной рендер продакшена (быстрее, безопаснее для 200 устройств), с записью решения и причины.

M5 — не назван обязательный тег Touch editor: из TOUCH-SUPPORT.md

Файл: docs/specs/179-device-icons-redesign.md (документ целиком)

docs/TOUCH-SUPPORT.md, раздел «Documentation rule»: «New editor feature specifications and code reviews must state one of: Touch editor: supported; Touch editor: best effort / intentionally degraded; Touch editor: not exposed.» ТЗ меняет интерактивный маркер (shell, hit area, focus/keyboard) на поверхности Device editor (§11: «Интерактивные маркеры в View/kiosk и Device editor получают tabindex="0"…»), то есть подпадает под правило, но нигде в документе буквально не заявляет ни один из трёх канонических тегов. Канонический документ подсистемы даёт готовый ответ («Device editor: Best effort» — из таблицы контракта), ТЗ просто не переносит его явным образом.

Требуется: добавить одну строку вида Touch editor: best effort / intentionally degraded (или supported, если автор считает keyboard/hit-area изменения полностью бесплатными для touch — решение автора, не владельца) в раздел §11 или §17.

L1 — Light-only combo-эталоны (Selected + Hover/Working/Green/Alert,

Focus + Alert) не отражены в golden-матрице

manifest.json для Light содержит пять составных QA-эталонов (Selected + Hover.svg и т.д.), у Dark таких файлов нет вовсе (не только не хватает файлов — узлы Figma для них не заведены). §16.4 (golden matrix) перечисляет одиночные состояния, но не комбинации Selected/Focus с semantic state отдельно для Dark. Поскольку приоритет слоёв (§7.3) декларативный и реализуется одним рендерером, а не набором ассетов, это не блокирует разработку — но стоит явно зафиксировать в golden-матрице, что комбинации проверяются для обеих тем логически, а не по образцу (в Dark образца нет). Снимается автором с записью либо на одну строку в §16.4.

L2 — избыточная оговорка «unavailable hover запрещён» для static_icon

§7.3 говорит про static_icon: «на интерактивной поверхности он сохраняет разрешённые hover/focus/click; unavailable hover запрещён». Действующее поведение static_icon, зафиксированное в docs/USER-GUIDE.ru.md:811-816, таково, что этот режим вообще не входит в ветку unavailable («не показывает… недоступность»). Формулировка ТЗ не противоречит этому, но звучит как отдельное правило для случая, который по документированному контракту не может произойти. Не блокирует; можно оставить как защитную формулировку или убрать как мёртвый кейс — на решение автора.

Проверено и признано корректным

• SHA-256 архива (63670C73E25D1E59DDAF1BE236F3D7F2FAC827B9B5D6DD4B77125EA9BC012025) совпадает с реально скачанным файлом по ссылке из issue.
• Геометрия shell/core: круговой shell — путь-круг с центром (63.5, 55.5) и радиусом 50.75 (диаметр 101.5), core — <rect> 80×80 с тем же центром. 101.5/127 ≈ 0.799, 80/101.5 ≈ 0.788 — оба числа в ТЗ (§7.1) подтверждены вычислением по реальному SVG, не переписаны на глаз.
• Цвета состояний (§7.2): hover/focus #0C82F0, active/working/unlocked #F0A00C, alert #F0410C, unavailable core #B5BAC1, high LQI #1DC21D, lock black — все сверены построчным grep по fill/stroke в соответствующих Light SVG и совпадают.
• Continuous/Short/Alert тайминги (кроме easing Short/Alert — см. M3): 3.6 с / scale 1→1.5 / opacity .55→0 для Continuous и 1.1 с × 3 с задержками 0/1.1/2.2 с для Short — оба подтверждены и текстовым документом архива, и реальными @keyframes.
• Обнаруженная и верно разрешённая ошибка пакета: Light/Zigbee LQI Low.svg действительно закрашен #F0A00C (тот же цвет, что Mid), а не красным. Утверждение ТЗ §9/§20.2 о том, что это ошибка экспорта и что production-эталон — red по текстовой спецификации и решению владельца, подтверждено — это пример правильно задокументированного разрешения конфликта источников, а не догадки.
• LQI-границы 40/180 согласуются с уже существующей документированной границей комнатного LQI-градиента (docs/USER-GUIDE.ru.md:873: «градиент от красного (≤40) до зелёного (≥180)») — решение владельца не произвольно, оно продолжает существующий продуктовый факт.
• Секьюрность: §11 явно исключает новый путь обхода подтверждения для замков/клапанов через клавиатуру — Enter/Space вызывают тот же существующий click handler. Инвариант docs/SCOPE.md («никогда не по тапу без подтверждения») не нарушается ни в одном пункте ТЗ.
• Совместимость (§12): поведение "Open → Save не материализует ripple_size/ripple_color при смене UI-default 3→1.5" явно и правильно учитывает существующий паттерн записи (d.rippleSize !== 3 ? … : null в src/houseplan-card.ts:18448) и предотвращает тихий сброс уже явно сохранённых значений.
• Обязательные разделы §7.1 PROCESS.md — все присутствуют: сценарий, что видит пользователь до/после, проблема, скоуп/не-скоуп, контракт поведения, UX/доступность, данные/миграция, i18n, AC1…AC14 с доказательством, план автотестов, риски, откат, release-артефакты.
• Трассируемость: docs/specs/README.md обновлён в том же коммите с двусторонней ссылкой issue↔ТЗ; коммит 517a710 несёт корректные трейлеры Issue: #179 и User-Visible: no.
• Открытых продуктовых вопросов владельцу нет — все решения, требующие продуктового выбора (unavailable hover, приоритет pulse-настроек, границы LQI, клавиатура), приняты владельцем в комментарии аналитики и перенесены в §4 ТЗ без искажений.

Чего не проверял

• Figma-фреймы (99:1290, 104:1539) напрямую не открывались — ревью ограничено содержимым архива, доступного по ссылке из issue; это тот же источник, которым пользовался автор ТЗ.
• Index.html/PNG-визуализации архива не открывались в браузере — ревью на этапе ТЗ смотрит на текст и код, не на артефакт для дизайнеров; визуальная проверка релевантна golden-этапу code review.
• Полная построчная сверка размеров 32 px и 96 px (только 56 px эталон проверен вычислением; 32/96 в ТЗ не квотируются отдельно, они делегированы таблице SPECIFICATION.md §8 без искажения).
• Производительность не измерялась (кода нет); M4 — это находка на уровне решения, а не измеренный факт деградации.
• Гейты typecheck/test/build/smoke/golden не запускались — на этапе ревью ТЗ продуктового кода не существует, раздел неприменим.

Итог

Ни одна находка не блокирует по существу — все пять Medium устранимы точечными правками текста ТЗ (это ревью самого текста, а не архитектурного решения), но без них AC1, AC8 и AC13 не выполняют собственное обещание доказуемости («соответствует §10», «соответствует пакету», «нет неизвестных perf-рисков»). Вердикт — жёлтый, возврат автору в рамках текущего issue.