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

SPEC-REVIEW-192-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/192
• ТЗ под ревью: тело issue #192 (лёгкий трек, файл docs/specs/ не создаётся — метка small подтверждена)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: лёгкий (small), лимит циклов ревью ТЗ — 2 (§4 PROCESS.md)
• Цикл: r1/2

Скоуп ревью

ТЗ #192: шкала «Оттенок» в общем компоненте hp-color-opacity (используется в 8 call sites House Plan) получает полноценный циклический hue-gradient на треке вместо нативной серой дорожки; accent-color продолжает управлять только thumb. Изменение затрагивает один файл (src/hp-color-opacity.ts), без миграции, i18n, backend или расширения touch-контракта.

Не в скоупе ревью: продуктовый код не написан (issue в S4-spec-review; ветки issue/192-* в репозитории нет — проверено git branch -r), поэтому реализация, тесты и гейты — предмет будущего код-ревью (PROCESS.md §2.7).

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком (актуальная редакция, включая §2.4/§2.5/§5/§7.1/§8).
2. Прочитано тело issue #192 и единственный комментарий — аналитика владельца (Matysh, authorAssociation: OWNER, 2026-08-19): оценка 4/10 · 2/10 · 3/10 · P3 · feature/polish, обоснование легитимности лёгкого трека, явное решение владельца по опциональному объёму («меняется только шкала «Оттенок»; отдельные градиенты S/V/opacity не нужны — это принятое предположение, продуктового вопроса нет»).
3. Прочитан src/hp-color-opacity.ts целиком (741 строка) и построчно сверены технические утверждения ТЗ:
   • Проблема (§«Проблема» ТЗ) подтверждена: .hue-range (строка 234-236) содержит только accent-color: var(--hp-picker-hue, #f00), трек остаётся нативным серым; input[type='range'] (строка 225-233) задаёт height: 40px — заявленная в ТЗ существующая интерактивная область подтверждена, а не выдумана.
   • .hue-range — единственный range с этим классом; saturation/value (строки 682, 689) и opacity (707) не имеют отдельного класса — scope .hue-range-селектором из §«Скоуп»/Risks реально изолирует только hue-трек.
   • accent-color: var(--hp-picker-hue, ...) и переменная hueColor (строка 653, 676) — существующий механизм, ТЗ верно ссылается на его сохранение, а не переизобретает.
4. Проверено, нет ли других hue-подобных range-элементов вне hp-color-opacity.ts, которые ТЗ должно было бы затронуть, но не затрагивает (по прецеденту Medium-1 из SPEC-REVIEW-57-r1, где ТЗ #57 молча пропустило часть call sites): grep -rn "type=\"range\"" src/*.ts вне hp-color-opacity.ts находит только _rangeInput() (houseplan-card.ts:14482-14495, обобщённый opacity/numeric slider для диалога «Общие настройки», без hue) и .colorrow input[type='range'] (styles.ts:2157, тот же класс). Ни один не является hue-контролом — скоуп ТЗ (только .hue-range внутри hp-color-opacity) реально полон, пропущенных hue-поверхностей нет.
5. Прочитан test/color-picker.test.mjs (50 строк) и demo/smoke_color_picker.mjs (144 строки) — оба существуют, названы в плане автотестов точно; текущий smoke уже проверяет hue.value = '120' → picker.color === '#00ff00' и shiftArrowUsesTenStep — заявленные в AC2 факты («120° даёт зелёный», «Shift+Arrow меняет на 10°») подтверждены существующим кодом теста, а не придуманы для ТЗ.
6. Проверен demo/golden/matrix.mjs: сцена decor-color-popover-mobile-ru (строка 269, theme: 'dark') существует и совпадает с описанием ТЗ; отдельной light-сцены этого picker пока нет — ТЗ корректно относит её к «при необходимости» в разделе «Затронутые файлы», а не выдаёт за уже существующую.
7. Прочитан docs/USER-GUIDE.ru.md:189-193 — термин «Оттенок» и описание палитры («Оттенок, насыщенность, яркость, точное значение HEX и прозрачность... доступны вместе») совпадают с текстом ТЗ; обещанное release-уточнение («шкала оттенка показывает spectrum») не противоречит и не переопределяет существующую формулировку.
8. Прочитан docs/TOUCH-SUPPORT.md, раздел «Documentation rule» (строки 142-154): требование буквальной строки Touch editor: …. ТЗ содержит ### Performance и touch → «Touch editor: picker поддерживается как в #57; hit area и события не меняются» — по факту покрывает требование (см. «Что проверено» ниже).
9. Проверен прецедент SPEC-REVIEW-137-r1.md (Low-4): golden-харнесс (demo/golden/matrix.mjs/harness.mjs) параметризует тему только как light/dark (emulateMedia({ colorScheme })), отдельного forced-colors emulation-пути нет — сверено с тем же выводом, актуальным и для AC3 этого ТЗ (см. Low-1 ниже).
10. Проверены docs/CHANGELOG.md, docs/CHANGELOG.ru.md — существуют, ссылки ТЗ на release-артефакты не ведут в никуда.
11. Проверено, что issue не помечен trivial: тип feature/polish, а не bug — trivial неприменим по критериям §5.1 корректно, как и пишет сам автор аналитики.

Гейты (typecheck/test/build) не прогонялись — на этапе ревью ТЗ продуктового кода нет; прогон гейтов не относится к этому этапу (PROCESS.md §2.7/§8).

Обязательные разделы (§7.1 PROCESS.md, лёгкий трек — тело issue)

Раздел	Есть	Комментарий
Сценарий (персона/поверхность/момент)	✅	персона, поверхность, момент названы явно
Что человек увидит до/после	✅	одна фраза «До»/«После», без терминов реализации
Проблема	✅	подтверждена чтением hp-color-opacity.ts (см. «Как проверялось» п.3)
Скоуп / не-скоуп	✅	скоуп полон — подтверждено отсутствием иных hue-поверхностей (п.4)
Контракт поведения и UX	✅	включает touch-строку (п.5 контракта)
Модель данных и миграция	✅	«нет изменений», обоснованно для presentation-only CSS
i18n	✅	«новых строк нет», используется существующий ключ
AC1…ACn с доказательством	✅	5 штук, у каждого назван способ доказательства
План автотестов	✅	unit/smoke/golden по отдельности, ссылается на реальные файлы
Риски	✅	таблица риск/мера, 4 строки, включая thumb-контраст и селектор-scope
Откат	✅	revert engine-specific стилей, без миграции
Release-артефакты	✅	commit/changelog/USER-GUIDE/golden — все ссылки на существующие механизмы

Присутствует также блок «Принятые предположения», корректно отделяющий технические допущения (равномерные CSS stops, Chromium-only browser smoke) от уже принятого владельцем продуктового решения по объёму (см. «Как проверялось» п.2).

Находки

Low-1 — AC3 не разделяет явно, какая часть критерия доказывается golden, а какая — только чтением кода

Файл: тело issue #192, раздел «Критерии приёмки», AC3.

AC3 требует одновременно: (a) spectrum/thumb читаемы в light/dark, (b) forced-colors не получает нечитаемую заливку, (c) reduced-motion не меняется — и называет одно доказательство на все три: «dark/light golden candidates + source-contract/code review». Как подтверждено в «Как проверялось» п.9, golden-харнесс параметризует тему только как light/dark; отдельного forced-colors emulation-пути нет. Формально ТЗ не лжёт: «dark/light golden» относится к пункту (a), а «source-contract/code review» — к (b) и (c), но эта граница не проведена явно внутри самого AC3. Тот же класс находки уже фиксировался как Low в SPEC-REVIEW-137-r1 (Low-4) и не блокировал приёмку.

Воспроизведение неоднозначности: код-ревьюер, сверяя «AC3 доказан golden-ом целиком?», должен самостоятельно вывести, что golden покрывает только light/dark-часть, а forced-colors/reduced-motion проверяются исключительно чтением CSS, а не эмуляцией браузера.

Решение ревьюера: Low, не блокирует. При реализации/код-ревью явно зафиксировать в хендоффе, что forced-colors и reduced-motion доказаны «проверено чтением, не исполнением», а golden покрывает только light/dark readability — снимаю находку без правки текста ТЗ, тем же способом, что и прецедент.

Что проверено и корректно

• Соответствие docs/SCOPE.md: задача — editor/settings usability polish общего компонента, используемого в J4/J6-поверхностях (настройка декора/комнат/устройств); не создаёт нового job'а, View/kiosk не затрагиваются.
• Легитимность лёгкого трека: сложность 3/10, одна поверхность (hp-color-opacity.ts), без миграции/i18n/backend/touch-контракта — критерии §5 PROCESS.md выполнены все одновременно; trivial корректно признан неприменимым (не bug).
• Продуктовый вопрос закрыт до написания ТЗ. Единственный потенциально продуктовый вопрос — объём видимых изменений («только Hue или все шкалы») — уже решён самим владельцем текстом комментария аналитики («В рамках #192 меняется только шкала «Оттенок»... продуктового вопроса владельцу нет»), а не додуман автором задним числом.
• Технический диагноз проблемы не голословен — подтверждён прямым чтением src/hp-color-opacity.ts:225-236 (см. «Как проверялось» п.3): трек .hue-range действительно остаётся нативным серым, accent-color красит только thumb.
• Скоуп реально полон — построчный поиск по src/*.ts не находит других hue-подобных range-элементов вне .hue-range; в отличие от прецедента SPEC-REVIEW-57-r1 (Medium-1, пропущенные call sites), здесь пропущенных hue-поверхностей нет.
• Существующие тестовые файлы и golden-сцена, на которые ссылается ТЗ, реальны — test/color-picker.test.mjs, demo/smoke_color_picker.mjs, decor-color-popover-mobile-ru в demo/golden/matrix.mjs:269 — не выдуманы, факты AC2 (120°→зелёный, Shift+Arrow→10°) уже покрыты текущим smoke-кодом.
• Touch-контракт корректно ограничен: ТЗ явно относит touch-поддержку picker к уже реализованной в #57, не расширяя её, и явно называет родительские редакторы desktop-first по docs/TOUCH-SUPPORT.md; строка **Touch editor:** picker поддерживается как в #57 по существу закрывает требование буквальной декларации из «Documentation rule» этого документа.
• AC1-AC5 однозначны, каждый снабжён допустимым по §2.5 PROCESS.md способом доказательства (unit/smoke/golden/code review), включая корректное делегирование полной изоляции (AC4) предрелизному golden-гейту, а не локальному прогону — соответствует PROCESS.md §8 («полные наборы — предрелизный гейт»).
• Откат тривиален и корректен — CSS-only изменение без миграции данных.
• Release-артефакты ссылаются на существующие файлы (docs/CHANGELOG.md, docs/CHANGELOG.ru.md, docs/USER-GUIDE.ru.md), формулировка уточнения не противоречит текущему тексту гайда.
• «Принятые предположения» корректно отделяют свободные технические решения реализации (интерполяция stops, Chromium-only smoke) от уже принятого продуктового решения по объёму — не маскируют продуктовый вопрос под техническое решение.

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

• Реализацию — её нет: issue в S4-spec-review, ветки issue/192-* не существует (git branch -r пуст по этому номеру) — проверено.
• Гейты typecheck/test/build/browser smoke/golden — не относятся к этапу ревью ТЗ; предмет будущего код-ревью (PROCESS.md §2.7/§8).
• python -m pytest tests_backend — backend не затрагивается ни кодом, ни ТЗ этой задачи.
• Реальный визуальный результат градиента в браузере (Chromium/Firefox track pseudo-elements, контраст thumb на разных секторах) — на этом этапе CSS не написан; заявленные риски (thumb теряется на ярком секторе, расхождение WebKit/Gecko) зафиксированы в ТЗ как риски с мерами, а не проверены исполнением.
• Точность числовых оценок аналитики (ценность 4/10, сложность 3/10, P3) по существу — поле владельца (PROCESS.md §2.2), уже принятое явным решением до написания ТЗ.
• Полный список всех <input type="range"> в demo/ и custom_components/ — поиск ограничен src/*.ts, как единственным местом, где мог бы находиться продуктовый hue-контрол; demo//backend не содержат собственных UI-контролов picker'а.

Вердикт

Зелёный. High: 0, Medium: 0, Low: 1 (неявное разделение доказательства AC3 между golden и code review для forced-colors/reduced-motion — тот же класс, что прецедент SPEC-REVIEW-137-r1 Low-4; снимается без правки текста ТЗ, фиксируется в хендоффе код-ревью). ТЗ корректно и проверяемо решает заявленный узкий скоуп: единственный потенциально продуктовый вопрос (объём видимых изменений) уже закрыт владельцем в комментарии аналитики, технический диагноз проблемы подтверждён чтением кода, скоуп реально полон (других hue-поверхностей вне .hue-range не существует), AC однозначны и снабжены допустимыми способами доказательства.

Вердикт: зелёный · цикл r1/2 · High: 0 · Medium: 0 → нет · Документ: docs/reviews/SPEC-REVIEW-192-r1.md