Merge pull request 'Архив OpenSpec: redesign (#65)' (#67) from chore/65-archive-redesign into main

openspec/specs/web-app/spec.md

@@ -38,15 +38,21 @@ SHALL очищать токен и показывать экран входа.
 ### Requirement: Оболочка и адреса
 Приложение SHALL открываться под префиксом `/app/` и иметь страницы `/app/board` (доска связей), `/app/issues` (список
 задач) и `/app/issues/{key}` (карточка задачи — окно поверх страницы, требование «Карточка задачи»); `/app` и `/app/` SHALL вести на `/app/board`, неизвестный путь —
-на страницу «не найдено» со ссылками на разделы. Верхняя панель SHALL содержать выпадающий список проектов рядом с
-названием («<метка> — <название>», текущий отмечен, в конце «＋ Новый проект…»; требование «Проект в приложении»),
-переходы «Доска», «Задачи» и действие «Сменить токен». Неожиданная ошибка отрисовки страницы SHALL показываться
-сообщением с кнопкой «Перезагрузить», не пустым экраном.
+на страницу «не найдено» со ссылками на разделы. Верхняя панель SHALL содержать название, выпадающий список проектов
+(«<метка> — <название>», текущий отмечен, в конце «＋ Новый проект…»; требование «Проект в приложении»), разделы
+«Доска связей» и «Задачи» сегментным переключателем (текущий отмечен `aria-current="page"`), блок данных Jira с
+действием «Обновить из Jira» (требование «Обновление из Jira»), переключатель темы (требование «Тема») и меню с
+действием «Сменить токен». На узких экранах панель SHALL переноситься на две строки без горизонтальной прокрутки.
+Неожиданная ошибка отрисовки страницы SHALL показываться сообщением с кнопкой «Перезагрузить», не пустым экраном.
 
 #### Scenario: Переход между разделами
 - **WHEN** на доске выбран раздел «Задачи»
 - **THEN** адрес — `/app/issues` с текущим проектом, показан список задач; «назад» возвращает на доску
 
+#### Scenario: Сменить токен
+- **WHEN** в меню верхней панели выбрано «Сменить токен»
+- **THEN** токен очищен, показан экран входа
+
 ### Requirement: Ошибки хаба
 Приложение SHALL различать ошибки запросов к хабу: 401 — экран входа; хаб не отвечает (сеть, 5xx) — сообщение
 «хаб не отвечает» с возможностью повторить, ранее загруженные данные остаются на экране; прочие 4xx — текст `detail`
@@ -72,15 +78,26 @@ SHALL очищать токен и показывать экран входа.
 кроме перечисленных в этом требовании и в требовании «Источник данных доски»: построение модели из `GET /board`, CSV
 фильтра Jira и JSON доски (`arm-ka-links/1`); дорожки по эпикам со свёрткой и перестановкой, служебные дорожки внизу;
 карточки с перетаскиванием, растяжкой, размером по содержимому и привязкой к сетке; стрелки связей с выравниванием;
-фильтры по спринтам и исполнителям; легенда со скрытием видов работ и типов связей; «+ соседи по связям», «⇄ передачи»,
-«скрыть без связей», «⚑ критический путь», «▥ по датам» с колонками дат и их растяжкой; ящик «Проблемы»; таблица
-связей; экспорт и импорт JSON; тема; «Сбросить раскладку». Раскладка, дорожки, фильтры и тема SHALL храниться в
+фильтры по спринтам и исполнителям; легенда со скрытием видов работ и типов связей; «соседи по связям», «только
+передачи», «скрыть без связей», «критический путь», «по датам» с колонками дат и их растяжкой; ящик «Проблемы»; таблица
+связей; экспорт и импорт JSON; «Сбросить раскладку». Раскладка, дорожки и фильтры SHALL храниться в
 `localStorage` под теми же ключами `graph-<имя>…`, что у `links.html`, с той же миграцией старых ключей.
 Результат построения модели, видимой выборки, критического пути и проблем SHALL совпадать с результатом `links.html`
-на одних и тех же данных и фильтрах. У карточки задачи (не у заглушки) SHALL быть значок «Открыть карточку»,
+на одних и тех же данных и фильтрах.
+
+Шапка доски (закреплена при прокрутке) SHALL содержать заголовок «Доска связей», счётчики (задачи из всех, соседи по
+связям, связи из всех, скрытые без связей), пометку источника, если на доске снимок из файла (с действием вернуться к
+данным хаба), событие доски, кнопку «Проблемы» со счётчиком и меню с действиями «Перечитать», «Загрузить файл…»,
+«Экспорт JSON», «Таблица связей», «Привязка к сетке» и «Сбросить раскладку» (с подтверждением). Под шапкой — панель
+управления: мультиселекты «Спринты» и «Исполнители», переключатели группы «Показать» («Соседи по связям», «Только
+передачи», «Скрыть без связей») и группы «Режим» («Критический путь», «По датам»), каждый с `aria-pressed` и прежней
+подсказкой. Под панелью — легенда, которая сворачивается кнопкой «Легенда»; свёрнутая показывает число скрытых видов
+работ и типов связей; состояние свёртки хранится в `localStorage` под ключом `jira-hub-legend`. «Обновить из Jira»,
+тема и «Сменить токен» — в верхней панели приложения, на доске их нет.
+
+У карточки задачи (не у заглушки) SHALL быть значок «Открыть карточку»,
 открывающий `/app/issues/{key}` окном поверх доски; ключ карточки по-прежнему открывает задачу в Jira. Пока окно открыто
-и после его закрытия доска SHALL сохранять прокрутку, раскладку, фильтры и строку состояния пакета. Действия «Сменить токен» в меню
-доски нет — оно в верхней панели приложения. Ещё два отличия от `links.html` (R-10, R-18): двойной щелчок по уголку
+и после его закрытия доска SHALL сохранять прокрутку, раскладку, фильтры и строку состояния. Ещё два отличия от `links.html` (R-10, R-18): двойной щелчок по уголку
 карточки меряет высоту по содержимому при новой ширине, а не при прежней; указатель при перетаскивании и растяжке
 захватывается на нажатом элементе, а не на карточке, поэтому двойной щелчок по уголку сбрасывает размер. Загрузка файла CSV/JSON доступна только после входа, с экрана входа её нет.
 Карточка задачи, статус Jira которой входит в `closed_statuses`, SHALL быть приглушена (полупрозрачна), под
@@ -108,7 +125,7 @@ SHALL очищать токен и показывать экран входа.
 - **THEN** адрес `/app/board`, доска показана с той же прокруткой и раскладкой, без повторной загрузки `GET /board`
 
 #### Scenario: Возврат из другого раздела
-- **WHEN** доска прокручена вниз, выбран раздел «Задачи», затем раздел «Доска»
+- **WHEN** доска прокручена вниз, выбран раздел «Задачи», затем раздел «Доска связей»
 - **THEN** доска показана с той же прокруткой
 
 #### Scenario: Закрытые на доске приглушены
@@ -116,66 +133,80 @@ SHALL очищать токен и показывать экран входа.
 - **THEN** карточки AURORA-1621 и AURORA-1622 и стрелка AURORA-1620 → AURORA-1621 приглушены, AURORA-1620 — нет;
   под указателем AURORA-1621 — в полную яркость; критический путь и ящик «Проблемы» те же, что без приглушения
 
+#### Scenario: Свёрнутая легенда
+- **WHEN** в легенде скрыт вид работы «тестирование», легенда свёрнута, страница перезагружена
+- **THEN** легенда свёрнута, рядом с кнопкой «Легенда» — «скрыто: 1»; карточек вида «тестирование» на доске нет
+
 ### Requirement: Источник данных доски
 Доска SHALL хранить явный источник данных — хаб или файл. Пока показан снимок из файла (CSV или JSON-снимок), ответы
 хаба SHALL его не заменять; «Перечитать» SHALL возвращать источник «хаб» и загружать `GET /board` заново без обращения к
-Jira. Импорт JSON в режиме хаба SHALL применять раскладку, дорожки и фильтры и перечитывать хаб. «Обновить из Jira»
-SHALL проверять агента (`GET /agent`; офлайн — предупреждение, пакет всё равно ставится), ставить
-`POST /refresh {full: true, author: "viewer"}`, опрашивать `GET /batches/{id}` каждые 3 с одним опросом до
-терминального статуса пакета и затем перечитывать `GET /board`. Кнопка «Обновить из Jira» SHALL быть недоступна,
-пока запрос `/refresh` в пути или пакет выполняется. Незавершённый пакет `refresh` с автором `viewer` SHALL
-подхватываться при каждой успешной загрузке из хаба, кроме перечитывания снимка после завершения собственного пакета; пакеты `viewer` с другими командами не подхватываются. Опрос пакета SHALL прекращаться при ответе 404 и после 5 ошибок
-«хаб не отвечает» подряд, с сообщением и снова доступной кнопкой. Шапка доски SHALL показывать
-источник данных (данные хаба на время последнего полного прогона; «из файла») и одно текущее событие (загрузка; пакет
-выполняется / выполнен / ошибка с текстом; хаб не отвечает — прежние данные, а при снимке из файла — «на доске снимок из файла»; агент офлайн — пакет поставлен; ошибка
-разбора файла — «файл не разобран: <причина>»); новое событие заменяет предыдущее целиком. Пока пакет выполняется,
-«Перечитать» и загрузка файла SHALL не стирать событие пакета.
+Jira. Импорт JSON в режиме хаба SHALL применять раскладку, дорожки и фильтры и перечитывать хаб. Шапка доски SHALL
+показывать источник данных (пометка «из файла» с именем файла; данные хаба пометки не имеют) и одно текущее событие
+доски (загрузка; хаб не отвечает — прежние данные, а при снимке из файла — «на доске снимок из файла»; ошибка разбора
+файла — «файл не разобран: <причина>»; раскладка и фильтры из JSON применены; ошибка); новое событие заменяет
+предыдущее целиком. События пакета обновления из Jira показывает верхняя панель приложения (требование «Обновление из
+Jira»), не шапка доски.
 
 #### Scenario: Поздний ответ хаба не затирает файл
 - **WHEN** запрос `GET /board` в пути, и в это время загружен CSV
 - **THEN** после ответа хаба на доске по-прежнему данные CSV с пометкой «из файла»
 
-#### Scenario: Нет второго полного прогона
-- **WHEN** нажата «Обновить из Jira» и, пока пакет выполняется, доска перерисована (фильтр, «Перечитать»)
-- **THEN** кнопка остаётся недоступной, в хабе один пакет, его опрашивает один опрос
-
-#### Scenario: Пакет пропал
-- **WHEN** опрос пакета получил 404
-- **THEN** опрос остановлен, показано сообщение, кнопка «Обновить из Jira» снова доступна
-
-#### Scenario: Пакет после «Перечитать»
-- **WHEN** пакет `viewer` поставлен с другой вкладки и не завершён, нажато «Перечитать»
-- **THEN** доска показывает «пакет #N выполняется» и по завершении перечитывает данные
-
-#### Scenario: «Перечитать» во время пакета
-- **WHEN** пакет `viewer` выполняется и нажато «Перечитать»
-- **THEN** шапка по-прежнему показывает «пакет #N выполняется»
+#### Scenario: Пакет завершился при снимке из файла
+- **WHEN** на доске снимок из CSV и завершился пакет обновления из Jira
+- **THEN** на доске по-прежнему данные CSV с пометкой «из файла»; после «Перечитать» — данные хаба
 
 #### Scenario: Хаб недоступен при снимке из файла
-- **WHEN** хаб не отвечает и загружен JSON-снимок доски, либо на доске снимок из CSV и хаб не ответил на перечитывание
-  снимка после завершения пакета
+- **WHEN** хаб не отвечает и загружен JSON-снимок доски
 - **THEN** шапка показывает «хаб не отвечает — на доске снимок из файла», а не «показаны прежние данные»
 
+#### Scenario: Нет второго полного прогона
+- **WHEN** нажата «Обновить из Jira» и, пока пакет выполняется, доска перерисована (фильтр, «Перечитать»)
+- **THEN** кнопка «Обновить из Jira» в верхней панели остаётся недоступной, в хабе один пакет, его опрашивает один опрос
+
+#### Scenario: Пакет пропал
+- **WHEN** опрос пакета получил 404, на доске данные хаба
+- **THEN** доска показывает прежние данные без своего события об ошибке; сообщение о пропавшем пакете — в верхней панели
+
+#### Scenario: Пакет после «Перечитать»
+- **WHEN** пакет `viewer` поставлен с другой вкладки и не завершён, на доске нажато «Перечитать»
+- **THEN** верхняя панель показывает «пакет #N выполняется», по завершении доска перечитывает данные
+
+#### Scenario: «Перечитать» во время пакета
+- **WHEN** пакет `viewer` выполняется и на доске нажато «Перечитать»
+- **THEN** верхняя панель по-прежнему показывает «пакет #N выполняется», шапка доски — без события пакета
+
 #### Scenario: Чужой пакет не подхватывается
-- **WHEN** незавершённый пакет автора `viewer` состоит из команд `ensure_fields`
-- **THEN** доска его не опрашивает, кнопка «Обновить из Jira» доступна
+- **WHEN** незавершённый пакет автора `viewer` состоит из команд `ensure_fields`, открыта доска
+- **THEN** доска и верхняя панель его не опрашивают, кнопка «Обновить из Jira» доступна
 
 ### Requirement: Список задач
-Страница `/app/issues` SHALL показывать задачи текущего проекта из `GET /issues?project=<текущий>` таблицей: ключ (открывает карточку задачи окном поверх списка), тема,
-тип, статус Jira, исполнитель, спринт, срок (`planned_end`, иначе `duedate`), эпик (имя эпика, иначе ключ), вид работы,
-признак «сосед» (относительно проекта); статуса по факту в списке нет. Фильтры SHALL соответствовать параметрам `GET /issues` (спринт, исполнитель, вид
-работы, статус Jira, метка, эпик, только соседи, поиск по ключу или теме, скрыть закрытые), храниться в query-строке
-адреса вместе с `project` и применяться сервером; варианты выпадающих списков SHALL браться из снимка `GET /board?project=<текущий>`; значение фильтра из адреса, которого нет среди
-вариантов, SHALL показываться в списке с пометкой «(нет на доске)». Флажок «скрыть закрытые» SHALL
-быть включён по умолчанию (в адресе ничего), снятый — `closed=1` в адресе; включённый — запрос с `hide_closed=1`,
+Страница `/app/issues` SHALL показывать задачи текущего проекта из `GET /issues?project=<текущий>` таблицей: ключ
+(открывает карточку задачи окном поверх списка) с пометкой «сосед» (относительно проекта), тема, статус Jira,
+исполнитель, срок (`planned_end`, иначе `duedate`; просроченный срок незакрытой задачи выделен), спринт, эпик (имя
+эпика, иначе ключ), вид работы, тип; статуса по факту в списке нет. Щелчок по строке (кроме ссылок и выделения текста)
+SHALL открывать карточку задачи так же, как ключ. Шапка страницы SHALL показывать число показанных задач.
+
+Фильтры SHALL соответствовать параметрам `GET /issues` (спринт, исполнитель, вид работы, статус Jira, метка, эпик,
+только соседи, поиск по ключу или теме, скрыть закрытые), храниться в query-строке адреса вместе с `project` и
+применяться сервером. На виду SHALL быть поиск, переключатель «Открытые | Все», переключатель «Только соседи» и
+кнопка «Фильтры» с числом выбранных выпадающих списков; шесть выпадающих списков (спринт, исполнитель, вид работы,
+статус Jira, метка, эпик) — в панели, которая раскрывается этой кнопкой; каждый выбранный список SHALL показываться
+снимаемой плашкой «<подпись>: <значение>» и под строкой фильтров должно быть действие «Сбросить», снимающее все шесть
+списков. Варианты выпадающих списков SHALL браться из снимка `GET /board?project=<текущий>`; значение фильтра из
+адреса, которого нет среди вариантов, SHALL показываться в списке с пометкой «(нет на доске)». Положение «Открытые»
+SHALL быть по умолчанию (в адресе ничего), «Все» — `closed=1` в адресе; «Открытые» — запрос с `hide_closed=1`,
 кроме случая, когда в фильтре «Статус Jira» выбран статус из `closed_statuses`. Параметр `fact_status` в адресе
-игнорируется. Задачи SHALL
-загружаться порциями по 50 строк; «Показать ещё» SHALL быть доступна, пока последняя порция полная.
+игнорируется. Задачи SHALL загружаться порциями по 50 строк; «Показать ещё» SHALL быть доступна, пока последняя
+порция полная.
 
 #### Scenario: Фильтр в адресе
 - **WHEN** выбран спринт «AWPCA_Спринт 2» и исполнитель
 - **THEN** адрес содержит `project=`, `sprint=` и `assignee=`, таблица — результат `GET /issues` с этими параметрами; открытие этого
-  адреса в новой вкладке показывает ту же выборку
+  адреса в новой вкладке показывает ту же выборку, кнопка «Фильтры» показывает 2, видны плашки спринта и исполнителя
+
+#### Scenario: Снять фильтр плашкой
+- **WHEN** выбраны спринт и исполнитель, нажат ✕ на плашке спринта
+- **THEN** в адресе нет `sprint=`, `assignee=` остался, таблица перезапрошена
 
 #### Scenario: Конец списка
 - **WHEN** вторая порция вернула 17 задач
@@ -189,13 +220,17 @@ SHALL проверять агента (`GET /agent`; офлайн — преду
 - **WHEN** список отфильтрован по спринту, прокручен и догружен «Показать ещё», открыта карточка задачи и окно закрыто
 - **THEN** адрес списка с тем же фильтром, в таблице те же строки, прокрутка та же
 
+#### Scenario: Щелчок по строке
+- **WHEN** в таблице щёлкнута ячейка темы строки AURORA-1620
+- **THEN** адрес `/app/issues/AURORA-1620`, карточка открыта окном поверх списка
+
 #### Scenario: Закрытые скрыты по умолчанию
 - **WHEN** открыт `/app/issues`, в зеркале задачи в статусах «В работе», «Готово», «Снято»
-- **THEN** флажок «скрыть закрытые» включён, запрос `GET /issues` с `hide_closed=1`, в таблице только «В работе»; после
-  снятия флажка адрес содержит `closed=1`, в таблице все три
+- **THEN** выбрано «Открытые», запрос `GET /issues` с `hide_closed=1`, в таблице только «В работе»; после выбора «Все»
+  адрес содержит `closed=1`, в таблице все три
 
 #### Scenario: Выбран закрытый статус
-- **WHEN** флажок «скрыть закрытые» включён и в «Статус Jira» выбрано «Готово»
+- **WHEN** выбрано «Открытые» и в «Статус Jira» выбрано «Готово»
 - **THEN** запрос `GET /issues?status=Готово` без `hide_closed`, в таблице задачи в статусе «Готово»
 
 ### Requirement: Карточка задачи
@@ -294,10 +329,11 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 ### Requirement: Сборка и разработка
 Приложение SHALL быть npm-проектом в `web/` (React, TypeScript, Vite) с точными версиями зависимостей и
 `package-lock.json`. `make web` SHALL устанавливать зависимости (`npm ci`) и собирать приложение в
-`src/jira_hub/web/app/`; каталог сборки не хранится в git. Шрифты и прочие ресурсы
-страницы SHALL входить в сборку: приложение не обращается к внешним адресам. `make check` SHALL запускать `uv run pytest`, проверку типов
-и линтер фронта и тесты фронта; зелёным считается только весь набор. `npm run dev` SHALL поднимать сервер разработки с
-прокси маршрутов API на хаб из `JIRA_HUB_URL` (по умолчанию тестовый `http://127.0.0.1:8791`).
+`src/jira_hub/web/app/`; каталог сборки не хранится в git. Шрифты (Mulish — текст интерфейса, IBM Plex Mono — ключи
+задач и исходники), иконки и прочие ресурсы страницы SHALL входить в сборку: приложение не обращается к внешним
+адресам. `make check` SHALL запускать `uv run pytest`, проверку типов и линтер фронта и тесты фронта; зелёным считается
+только весь набор. `npm run dev` SHALL поднимать сервер разработки с прокси маршрутов API на хаб из `JIRA_HUB_URL` (по
+умолчанию тестовый `http://127.0.0.1:8791`).
 
 #### Scenario: Сборка с нуля
 - **WHEN** в чистом checkout выполнен `make web`
@@ -305,7 +341,7 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 
 #### Scenario: Без интернета
 - **WHEN** приложение открыто на машине без доступа в интернет
-- **THEN** страница не запрашивает ресурсов вне хаба, текст набран IBM Plex Sans
+- **THEN** страница не запрашивает ресурсов вне хаба, текст набран Mulish, ключи задач — IBM Plex Mono
 
 ### Requirement: Разметка Jira в карточке
 Описание задачи и текст каждого комментария в карточке SHALL показываться отрендеренной вики-разметкой Jira (хаб
@@ -379,10 +415,10 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 в `GET /projects`, иначе первый из `GET /projects`; выбранный проект записывается в адрес без новой записи истории.
 Проекта из адреса нет в `GET /projects` — страница SHALL показывать «проект <метка> не найден» и выпадающий список
 проектов вместо данных. Проектов нет — доска и список SHALL показывать приглашение создать проект («＋ Новый проект…»).
-Переходы «Доска» / «Задачи» SHALL сохранять текущий проект. Карточка задачи (`/app/issues/{key}`) от проекта не зависит.
+Переходы «Доска связей» / «Задачи» SHALL сохранять текущий проект. Карточка задачи (`/app/issues/{key}`) от проекта не зависит.
 
-Доска SHALL загружать `GET /board?project=<текущий>`; «Обновить из Jira» — как прежде, `POST /refresh {full: true}`,
-обновляет все проекты. Раскладка, дорожки и фильтры доски в `localStorage` SHALL храниться отдельно для каждого проекта;
+Доска SHALL загружать `GET /board?project=<текущий>`; «Обновить из Jira» — `POST /refresh {full: true}`, обновляет все
+проекты. Раскладка, дорожки и фильтры доски в `localStorage` SHALL храниться отдельно для каждого проекта;
 у проекта `AWPCA` — на прежних ключах (раскладка, сделанная до проектов, сохраняется). Фильтр спринтов SHALL
 показываться, только если хотя бы у одной своей задачи снимка (`neighbor = false`) есть спринт; иначе — «колонки
 «Спринт» нет — показаны все задачи».
@@ -390,8 +426,7 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 Форма «Новый проект» (пункт «＋ Новый проект…» выпадающего списка) SHALL открываться окном поверх страницы: метка,
 название, номер доски Jira (необязательно; подсказка «scrum или kanban определится сам»). «Создать» — `POST /projects`
 с автором `viewer`; ошибка хаба 409/422 — текст `detail` рядом с кнопкой, окно остаётся открытым; успех — окно
-закрывается, текущим становится новый проект, доска подхватывает пакет обновления (`refresh` автора `viewer`) и
-показывает его ход.
+закрывается, текущим становится новый проект, верхняя панель показывает ход пакета обновления из ответа (`batch_id`).
 
 #### Scenario: Первый вход после выкатки
 - **WHEN** открыт `/app/board` без `project`, в `localStorage` выбора нет, проекты `AWPCA` и `STOCKS_DRRK`
@@ -408,7 +443,7 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 #### Scenario: Создание проекта из формы
 - **WHEN** в форме введены `STOCKS_DRRK`, «Запасы ДРРК», доска пусто; нажато «Создать»
 - **THEN** `POST /projects {label: "STOCKS_DRRK", name: "Запасы ДРРК", author: "viewer"}`; текущий проект — `STOCKS_DRRK`;
-  шапка доски показывает «пакет #N выполняется»
+  верхняя панель показывает «пакет #N выполняется»
 
 #### Scenario: Метка занята
 - **WHEN** в форме введена метка `awpca`, хаб ответил 409
@@ -417,3 +452,80 @@ SHALL сообщать об этом с кнопкой «Закрыть»; ха
 #### Scenario: Канбан-проект
 - **WHEN** текущий проект — `STOCKS_DRRK`, ни у одной своей задачи снимка нет спринта (у соседа из `AWPCA` спринт есть)
 - **THEN** вместо фильтра спринтов — «колонки «Спринт» нет — показаны все задачи»
+
+### Requirement: Дизайн-система
+Приложение SHALL следовать дизайн-системе AURA (handoff AURA-xlsx-tool 29.09.2026, Figma «Универсалки») в светлой и
+тёмной темах. Токены — цвета по семантическим ролям для обеих тем, типографика, отступы с шагом 4 px, радиусы, высоты
+контролов, фокус, движение — SHALL быть определены в `web/src/styles/tokens.css` (вместе с токенами приложения: палитра
+видов работ, приоритеты, стрелки и дорожки доски); прочие файлы стилей MUST NOT содержать литералов цвета и SHALL
+брать цвета из токенов. Экраны SHALL собираться из компонентов `web/src/ui/` (кнопки, кнопка-иконка, сегментный
+переключатель, переключатель темы, поле с подписью, поле ввода и поиска, выпадающий список, флажок, бейдж, снимаемая
+плашка, сообщение, панель, шапка страницы, окно, меню). Геометрия: контролы 32 px (крупные 40 px) с радиусом 10 px,
+кнопки — «таблетки», панели — радиус 16 px, окна — радиус 20 px, флажок 16×16 px; текст Regular 14/20, подписи
+Semibold 14/20, заголовок страницы Bold 20/28. Страницы, кроме доски, SHALL занимать контейнер до 1440 px по центру с
+боковым отступом 24 px (16 px на экранах уже 640 px); доска — всю ширину окна с отступом 24 px. Иконки — SVG из
+сборки, не символы текста. Каждый интерактивный элемент SHALL иметь видимое кольцо фокуса; цвет MUST NOT быть
+единственным признаком состояния.
+
+#### Scenario: Цвет вне токенов
+- **WHEN** в любом `*.css` в `web/src`, кроме `styles/tokens.css`, появился литерал цвета
+- **THEN** тесты фронта падают с именем файла и литералом
+
+#### Scenario: Тёмная тема
+- **WHEN** выбрана тёмная тема
+- **THEN** канва `#181818`, поверхности `#1f1f1f`, основной текст `#f2f4f2`, основное действие `#69a93d` на всех
+  страницах, в окнах и меню
+
+### Requirement: Обновление из Jira
+Действие «Обновить из Jira» SHALL быть в верхней панели приложения и доступно с любой страницы. Оно SHALL проверять
+агента (`GET /agent`; офлайн — предупреждение, пакет всё равно ставится), ставить `POST /refresh {full: true, author:
+"viewer"}` и опрашивать `GET /batches/{id}` каждые 3 с одним опросом до терминального статуса пакета. Кнопка SHALL быть
+недоступна (с признаком загрузки), пока запрос `/refresh` в пути или пакет выполняется. Незавершённый пакет автора
+`viewer`, первая команда которого — `refresh`, SHALL подхватываться при входе в приложение и после каждой успешной
+загрузки снимка доски, кроме перечитывания снимка после завершения собственного пакета; пакеты `viewer` с другими
+командами не подхватываются. Опрос SHALL прекращаться при ответе 4xx (404 — «пакета нет в хабе») и после 5 ошибок
+«хаб не отвечает» подряд, с сообщением и снова доступной кнопкой. По завершении пакета приложение SHALL перечитывать
+снимки досок, списки задач, открытую карточку и список проектов; доска, показывающая снимок из файла, его не заменяет.
+Пакет, поставленный формой «Новый проект», SHALL опрашиваться так же сразу после создания.
+
+Верхняя панель SHALL показывать блок данных Jira: состояние агента («агент на связи» / «агент офлайн», по `GET /agent`
+при входе и раз в 60 с), время последнего полного обновления («данные на ДД.ММ ЧЧ:ММ» по `last_sync` снимка доски
+текущего проекта, «полного обновления не было», если его нет) и одно текущее событие пакета: в очереди / выполняется (с
+оставшимся временем, с пометкой «агент офлайн» и «хаб не отвечает, повтор»), выполнен, не выполнен с текстом ошибки,
+отменён, опрос остановлен с причиной, хаб не ответил на постановку; новое событие заменяет предыдущее, «выполнен»
+исчезает через 10 с.
+
+#### Scenario: Обновление со списка задач
+- **WHEN** открыт `/app/issues`, нажато «Обновить из Jira», пакет выполнен
+- **THEN** в хабе один пакет `refresh` автора `viewer`; список задач перезапрошен; верхняя панель показывала «пакет #N
+  выполняется», затем «пакет #N выполнен»
+
+#### Scenario: Один прогон на всё приложение
+- **WHEN** нажата «Обновить из Jira» и, пока пакет выполняется, выполнен переход между разделами и «Перечитать» на доске
+- **THEN** кнопка остаётся недоступной, в хабе один пакет, его опрашивает один опрос
+
+#### Scenario: Опрос получил 404
+- **WHEN** опрос пакета получил 404
+- **THEN** опрос остановлен, верхняя панель показывает «пакета нет в хабе», кнопка «Обновить из Jira» снова доступна
+
+#### Scenario: Пакет с другой вкладки
+- **WHEN** пакет `viewer` с командой `refresh` поставлен с другой вкладки и не завершён, приложение открыто
+- **THEN** верхняя панель показывает «пакет #N выполняется» и по завершении данные перечитываются
+
+#### Scenario: Пакет с другими командами
+- **WHEN** незавершённый пакет автора `viewer` состоит из команд `ensure_fields`
+- **THEN** приложение его не опрашивает, кнопка «Обновить из Jira» доступна
+
+#### Scenario: Агент офлайн
+- **WHEN** `GET /agent` отвечает `online: false` и нажато «Обновить из Jira»
+- **THEN** пакет поставлен, событие — «агент офлайн — пакет выполнится, когда он выйдет на связь; пакет #N в очереди…»
+
+### Requirement: Тема
+Переключатель темы SHALL быть в верхней панели приложения: два положения — светлая и тёмная. Выбор SHALL храниться в
+`localStorage` под ключом `graph-theme` (`light` / `dark`), как у прежней доски; без сохранённого выбора или со
+значением `""` тема SHALL следовать настройке системы, и переключатель показывает её. Тема применяется до первой
+отрисовки, без мигания.
+
+#### Scenario: Выбор темы сохраняется
+- **WHEN** в системе светлая тема, переключатель переведён в «тёмная», страница перезагружена
+- **THEN** приложение в тёмной теме, в `localStorage` `graph-theme` = `dark`