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

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

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

Скоуп ревью

Проверялось только ТЗ как артефакт этапа S4-spec-review: обязательные разделы §7.1 PROCESS.md, однозначность и доказуемость AC1…AC10, соответствие docs/SCOPE.md (J1/J2), docs/USER-GUIDE.ru.md, docs/TOUCH-SUPPORT.md, и отдельно — фактическое соответствие числовых утверждений ТЗ нормативному источнику: тому же архиву дизайнера, что и в #179, плюс текущей реализации в src/styles.ts (описанной как «до»). Продуктовый код по #211 не существует (issue не дошёл до S5-ready, диапазон origin/dev..HEAD содержит только docs/specs/211-*.md и правку docs/specs/README.md), поэтому код не проверялся и гейты §8 PROCESS.md к этому циклу неприменимы.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком.
2. Прочитано тело issue #211 и оба комментария (аналитика + «ТЗ готово»), а также issue #179 целиком — тело и все 15 комментариев обоих циклов ревью ТЗ и код-ревью, чтобы знать, какие решения владельца уже приняты и что именно было принято/исправлено там (M1–M5, L1–L2 в SPEC-REVIEW-179-r1.md/r2.md).
3. Прочитан файл ТЗ 211-device-icons-visual-parity.md целиком (354 строки) и docs/specs/179-device-icons-redesign.md целиком — как источник приоритета №4 по собственной цепочке разрешения расхождений ТЗ #211.
4. Архив дизайнера скачан заново и распакован (curl по той же ссылке из тела issue #179, sha256sum совпал с указанным в ТЗ #211 63670C73E25D1E59DDAF1BE236F3D7F2FAC827B9B5D6DD4B77125EA9BC012025) — независимая проверка, не пересказ ТЗ #179:
   • подтверждена геометрия shell/core (<path>/<rect> в Light/Dark Icon Default*.svg: shell — круг диаметром 101.5, core — <rect rx="40"> 80×80, отношение 1.26875);
   • подтверждён pill value-badge (Double Default Right.svg: Frame_2 — путь y: 24…87, высота 63 = 0.7875×80, радиус скруглений 31.5 = 0.39375×80, то есть ровно половина высоты);
   • подтверждены цвета состояний построчным grep по fill/stroke в Icon Hover/Active/Alert Value/Selected/Focus Visible/Lock/Unlock.svg для обеих тем;
   • подтверждён stroke="#252525" stroke-opacity="0.75" в Dark/Icon Default No Blur.svg (Dark shell default) и stroke-dasharray "6 6" в Virtual Device *.svg (Virtual shell);
   • подтверждена сама регрессия, зафиксированная в Dark/Unlock.svg архива (fill="#1DC21D", зелёный) — и то, что ТЗ №211 корректно, вслед за ТЗ #179, отвергает этот файл в пользу решения владельца («Unlock — янтарный в обеих темах»), а не проецирует его буквально;
   • измерена реальная bounding box глифа (svgpathtools, путь id="Vector") в Icon Default/Hover/Active/Default No Blur.svg (общий «колокольчик») и в Lock.svg/Unlock.svg — см. M1 ниже;
   • проверено существование каждого документа, который ТЗ №211 §4 называет нормативным источником (SPECIFICATION.md, DEVELOPER_HANDOFF.md, ACTIVE_ANIMATION_SPEC.md, COMPARISON_NOTES.md) — см. L1.
5. Сверено с текущей реализацией src/styles.ts (строки 1860–2214): каждое из шести «подтверждённых расхождений» ТЗ §3 сопоставлено построчно с кодом — border-radius: 28% (:1961), --mdc-icon-size: … * 0.62 (:1984), value-section border-radius: … * 0.18 при высоте .7875 (:2180,:2188), безусловный border: 1px solid #BCBCBC без тёмного варианта (:1912).
6. Прочитаны релевантные фрагменты docs/USER-GUIDE.ru.md (термин «маркер», отсутствие конфликтующей терминологии) и целиком docs/TOUCH-SUPPORT.md («Documentation rule», канонические теги Touch editor: …).
7. Код не запускался, гейты не прогонялись — на этапе ревью ТЗ кода нет.

Находки

M1 — целевое соотношение «MDI viewport = 0.5 × core» не подтверждено ни одним источником архива и расходится с прямым измерением SVG

Файл: docs/specs/211-device-icons-visual-parity.md:44-45 (§3, п.2), :123 (§7.1, таблица), AC1 (:241-244)

ТЗ утверждает как факт: «пакет использует 40 × 40 внутри core 80 × 80, то есть 0.5 × core» и заносит MDI viewport | width = height = 0.5 в таблицу геометрического контракта §7.1 с допуском не более 0,5 CSS px на 32/56/96 px (тот же допуск, что и для проверенно точных чисел вроде 1.26875 и 0.7875). Это число прямо используется в AC1 как критерий приёмки.

Проверка источников:

• SPECIFICATION.md, DEVELOPER_HANDOFF.md, ACTIVE_ANIMATION_SPEC.md, PACKAGE_ANNOTATION.txt — ни один не называет размер/долю icon-viewport внутри core; SPECIFICATION.md §8 говорит только о shell/core/border/shadow.
• Прямое измерение bounding box самого глифа (svgpathtools, путь id="Vector") в реальных SVG даёт не 0.5: Icon Default/Hover/Active/Default No Blur.svg (общий глиф-колокольчик) — 33.33 × 33.33 = 0.417 × core; Lock.svg/Unlock.svg — 26.67 × 35.0 = 0.333–0.4375 × core.
• Единственное место архива, где встречается ровно 50%, — файл Index.html (.new .glyph { width: 50%; height: 50%; }), интерактивный demo-компаратор «старый/новый» дизайн. Но: (а) он не входит в список источников §4 ТЗ (там перечислены только owner-решения, три .md-документа, «SVG архива» и ТЗ #179 — без Index.html); (б) сам этот демо-файл использует приближённые круглые px-значения (--core-size: 42px при --s: 56px, то есть core/marker ≈0.75, тогда как в реальных экспортных SVG это отношение 0.7882 — расхождение ~5%), то есть он иллюстративный прототип, а не пиксель-точная копия экспортных assets.

Итог: 0.5 — правдоподобное производное значение (bbox глифа + типичный внутренний padding самих MDI-иконок ≈10–15% могли бы дать assigned-frame ≈39–41), но ТЗ подаёт его как прямую цитату архива наравне с числами, которые я независимо проверил и подтвердил буквально (1.26875, 0.7875, 0.39375, все цвета состояний). Ни один текстовый документ этого числа не называет, а единственный SVG-источник с буквальным 50% не упомянут в §4 и сам не является пиксель-точным.

Почему это важно: AC1 — единственный количественный критерий именно для формы/масштаба глифа, то есть сердцевина задачи «маркер визуально совпадает с пакетом». Раздел §11 требует построить независимую таблицу «Reference SVG ↔ Runtime» именно для того, чтобы новый golden не мог сам стать себе эталоном (это и есть причина, по которой заведён #211). Если строка «Reference SVG» для glyph viewport унаследует непроверенное число 0.5, фикстура будет защищать неверную/неподтверждённую цель с той же уверенностью, что и корректные строки — то есть повторит тот самый механизм регрессии, из-за которого возник этот баг.

Требуется одно из:

1. явно сослаться на Index.html как источник и показать расчёт (bbox + допущение о внутреннем padding MDI) в §4/§7.1, чтобы ревьюер кода видел основание числа, а не готовый вывод; либо
2. перенести именно эту строку в §16 «Принятые технические предположения» — как единственную геометрическую величину, не имеющую прямого текстового или однозначного SVG-подтверждения, — и явно разрешить реализации/ревью скорректировать её при визуальном сравнении с реальным MDI-глифом (в отличие от статичного примера-«колокольчика» из пакета).

Находка в скоупе задачи (это её собственный AC1); блокирующей не является — одна Medium без High даёт жёлтый вердикт и правку в этом же ТЗ.

L1 — §4 называет нормативным источником несуществующий файл COMPARISON_NOTES.md

Файл: docs/specs/211-device-icons-visual-parity.md:62-63

Порядок приоритета источников перечисляет «SPECIFICATION.md, DEVELOPER_HANDOFF.md, ACTIVE_ANIMATION_SPEC.md и COMPARISON_NOTES.md архива #179». В реально скачанном и распакованном архиве (тот же SHA-256, что и в ТЗ) присутствуют README.md, SPECIFICATION.md, DEVELOPER_HANDOFF.md, ACTIVE_ANIMATION_SPEC.md, PACKAGE_ANNOTATION.txt, manifest.json, Index.html — файла COMPARISON_NOTES.md нет и не было ни в одной версии архива, которую видел я или которую цитировал разбор #179.

Не блокирует ни один AC (все содержательные факты, которые могли бы там быть, взяты из реально существующих документов и подтверждены), но при реализации кто-то потратит время, разыскивая несуществующий файл как «третий по приоритету» источник истины. Снять правкой — убрать имя файла из списка либо заменить на реально существующий (вероятно, опечатка/перенос из не-#179 контекста).

L2 — обязательный тег Touch editor: … присутствует по смыслу, но не дословно

Файл: docs/specs/211-device-icons-visual-parity.md:183-186 (§8)

docs/TOUCH-SUPPORT.md («Documentation rule») требует, чтобы спецификации, затрагивающие редактор, буквально называли один из трёх канонических тегов: Touch editor: supported / best effort / intentionally degraded / not exposed. §8 ТЗ №211 говорит «Device editor остаётся desktop-first / touch best effort» — по смыслу корректно (совпадает с уже принятым в #179 «best effort / intentionally degraded») и задача не меняет интерактивность (в отличие от #179, где отсутствие этого тега было Medium именно потому, что там вводился новый keyboard/focus контракт), поэтому не блокирует. Для единообразия с остальными спецификациями и grep-совместимости стоит заменить на буквальный Touch editor: best effort / intentionally degraded. — на решение автора.

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

• SHA-256 архива совпадает с указанным в ТЗ; архив идентичен тому, что проверялся в цикле #179.
• Геометрия shell/core (1.26875) и value-badge pill (0.7875 высота, 0.39375 радиус = половина высоты) — оба подтверждены прямым измерением реальных <path>/<rect> координат, не переписаны на глаз.
• Описание регрессии (§3, пп. 1, 3, 4) сверено построчно с текущим src/styles.ts и подтверждено буквально: border-radius: 28% (core не круг), border-radius: calc(... * 0.18) при pill-высоте 0.7875 (радиус должен быть 0.39375), безусловный светлый #BCBCBC shell-stroke без тёмного варианта.
• Цвета состояний (§7.3): hover #0C82F0, active/unlock #F0A00C, alert #F0410C, Dark shell #252525/opacity .75, virtual stroke-dasharray 6 6, selected #F0A00C ring r=41.5, focus #0C82F0 ring r=41.5 поверх видимого base shell — все сверены построчным grep по реальным SVG обеих тем и совпадают с таблицей §7.2/§7.3.
• Корректно разрешённая ошибка пакета: Dark/Unlock.svg в архиве реально закрашен зелёным (#1DC21D, устаревшая dark-ревизия) — ТЗ №211 правильно, вслед за уже принятым решением владельца в #179, отвергает этот файл в пользу «янтарный в обеих темах», а не проецирует его буквально.
• Обязательные разделы §7.1 PROCESS.md — все присутствуют: сценарий, что видит пользователь до/после, проблема, скоуп/не-скоуп, контракт поведения, UX/touch/доступность, данные/совместимость/i18n, AC1…AC10 с доказательством, план автотестов, риски, откат, release-артефакты.
• Скоуп корректно ограничен восстановлением уже принятого дизайна #179 — никаких новых состояний, resolvers, LQI-порогов, actions или config-модели не вводится (§6); это отличает задачу от #179 и обосновывает отсутствие открытых продуктовых вопросов владельцу без blocked.
• Трассируемость: docs/specs/README.md обновлён тем же коммитом с двусторонней ссылкой issue↔ТЗ; коммит 93200eb несёт трейлеры Issue: #211 и User-Visible: no — корректно для документации без изменения продукта.
• Секьюрность и touch-инвариант не задеты: §8 явно называет secure confirmation/keyboard/dialog focus return как поведение, которое обязано остаться без изменений, а не переопределяет его.

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

• Figma-фреймы (99:1290, 104:1539) напрямую не открывались — ревью ограничено содержимым скачанного архива, тем же источником, которым пользовался автор ТЗ.
• Полная построчная сверка всех Double/Text/LQI SVG всех четырёх сторон — выборочно проверены Double Default Right.svg (value pill) и сопутствующий Frame_2; остальные три стороны и Text *.svg не измерялись отдельно, поскольку геометрия pill и текста не зависит от стороны по самому контракту §7.1 ТЗ.
• PNG-визуализации архива не открывались — не источник геометрических фактов, только иллюстрация.
• Производительность не измерялась (кода нет).
• Гейты typecheck/test/build/smoke/golden не запускались — на этапе ревью ТЗ продуктового кода не существует, раздел неприменим.

Итог

Находка блокирующей силы не имеет: единственный Medium (M1) устраняется точечной правкой текста ТЗ — либо явной ссылкой на источник и расчёт, либо переносом числа в блок технических предположений §16, — без изменения скоупа, AC или архитектурного решения. Два Low — на усмотрение автора. Вердикт — жёлтый, возврат автору в рамках текущего issue.