# Аудит неоднозначностей интерфейса

Дата: 2026-07-23. Основа: актуальный `main` после синхронизации с GitLab.

## Закрыто в итерации 2026-07-23

| Проблема | Почему возникали разные реализации | Решение |
| --- | --- | --- |
| Сайдбар без фото; имя пользователя в разных местах | Место аватара нигде не было специфицировано; SSO_AVATAR задавал только источник фото; composition guard запрещал «добавлять Avatar», а куда его ставить — никто не говорил | Контракт идентичности (решение владельца): блок `.bark-sidebar__user` в футере сайдбара — фото из SSO (fallback — инициалы) + имя + email + icon-only `Выйти`; `barkone` — задокументированное легаси-исключение (аватар в шапке). Шапка страницы аватара не несёт. Шаблоны + тесты + check |
| Logout выглядел по-разному после появления user-блока | Полноширинная кнопка конфликтовала с блоком идентичности | Logout стал icon-only 40×40 в правом конце `.bark-sidebar__user`; `Выйти` — aria-label/title; busy — spinner + `Выходим…` |
| Инициалы считались по-разному | Формулы не существовало | Единая `initialsFromName()` в адаптере + тесты |
| Страницы разной плотности, часто очень воздушные | Каркас страницы не имел ни одного числа: паддинги страницы/панелей, разрывы секций, высоты строк не заданы; «плотность под задачу» была неограниченной | Закреплённые числа: `.bark-main` `24/32/40`, секции 24, сетки 16, панель 20 (`--dense` `12/16`), таблицы 44/36; два режима плотности; правило «первый экран 1440×900 = шапка + ≥2 ряда контента» |
| Таблицы каждый раз новые | Базовой спеки не было | `.bark-table`: caption-шапка 40px, строки 44/36, числа mono вправо, hover `--surface-2`, без zebra |
| KPI-карточки и empty states произвольные | Спеки не было | `.bark-kpi` (mono 24/600, паддинг 16×20) и `.bark-empty` (регион, не экран) |
| Favicon «не по правилам» | Генератор был, но HTML-подключение и приёмка не описаны; PNG-этап легко пропустить | `favicon.head.html` (канонический блок с 5 пунктами приёмки) — шаблон + генерация для каждого продукта + проверка в check |
| Разные transition/слои | Motion-токенов и z-шкалы не было | `--motion-*`, `--ease-out`, `--z-*` закреплены |
| Фильтры списков каждый раз новые | Inline vs popover vs drawer не было решено | Тулбар `.bark-toolbar` 32px: поиск + ≤3 inline-фильтра, дальше один popover «Фильтры»; accent-чипы применённых фильтров + «Сбросить»; состояние в URL; пустой результат — `.bark-empty` со сбросом |
| Пагинация произвольная или infinite scroll | Правила не было | `.bark-pagination`: обязательна >50 строк, размеры 25/50/100 (default 50), mono-счётчик «1–50 из 1 234», prev/next 32px; infinite scroll в таблицах запрещён |
| Toast vs inline banner | Выбор и длительности не были решены | Единый toast-стек (`toast.snippet.js`): справа внизу, ≤3, ok/info 5s / warn 8s / bad до закрытия, role=status/alert; `.bark-alert` — для постоянных состояний; правило «toast = событие, alert = состояние, модалка = решение, у поля = валидация» |
| Даты/числа/деньги в каждом продукте свои («3.55M», «только что назад», локальная TZ) | Локаль, таймзона, лестницы и денежный формат нигде не были решены | `docs/DATA_FORMATS.md` + единый форматтер `templates/format.snippet.js`: ru-RU, всё время в МСК, `ДД.ММ.ГГГГ`/24ч, `1 234,56 ₽`, `тыс./млн`, лестницы относительного времени и длительностей, диапазоны с en dash, телефоны РФ; юнит-тесты на фиксированных датах |
| Chart library не выбрана | Решение было отложено | **Apache ECharts 5+** для новых графиков: тема Bark из живых токенов (`chart-theme.snippet.js`), self-hosted bundle (CDN запрещён), палитра серий `--accent → #2a6fdb → #8a63d2 → #5c6b7a`, максимум 4 серии; легаси сохраняет свою библиотеку на тех же токенах |
| Сортировка и действия строк каждый раз новые | Направления, иконки и место деструктивных действий не были решены | Ровно одна активная сортировка (`aria-sort`, числа/даты desc-first, состояние в URL); действия — ≤2 icon-кнопки 32px, дальше kebab + `.bark-menu` (180/36px, `--z-dropdown`); деструктивные — только в меню с подтверждением |
| Внедрение медленное, версия бренда в продукте неизвестна | Дистрибуция «vendor copy» без версий; зеркала токенов правились руками; проверки жили только в бренд-репо | SemVer + CHANGELOG + тег `vX.Y.Z` → publish в GitLab npm registry (`@bark/brand-system`); append-only `dist/vX.Y.Z/` для no-build продуктов; `Bark UI vX.Y.Z` в мета сайдбара; `bark-check` + CI-include `ci/bark-brand.gitlab-ci.yml` в каждом продукте; зеркала CSS/Tailwind генерируются из токенов (`npm run build:tokens`, `--check` в валидаторе) |

## Закрыто в этой итерации

| Проблема | Почему возникали разные реализации | Решение |
| --- | --- | --- |
| Шрифты были глубоко в guide | Роли забывались при подключении | Формула вынесена в README/главную/AGENTS |
| H1/H2 использовали logo font | Red Hat Display технически выходил за пределы логотипа | Все interface headings переведены на Onest; добавлен typography guard |
| Иконки назывались Lucide без источника | Можно было подключить похожий pack | Зафиксирован только `https://lucide.dev/` |
| Sidebar scroll | Длинная nav двигала footer или перекрывалась им | Скроллится только `.bark-sidebar__scroll` |
| Footer | `margin-top:auto` не гарантировал поведение при overflow | Bottom zone закреплена внутри `100dvh` sidebar |
| Logout | Кнопка могла находиться в nav/profile menu и выглядеть по-разному | Единый `Выйти` + Lucide `LogOut` закреплён внутри footer |
| Theme switch | Разное место и компактная ширина | Desktop: full-width control внизу sidebar |
| Каталог продуктов | `barkledger`/`barkhr` были в токенах, но не на главной | Продукты выведены в README и Pages |
| Склад | Не было короткого однозначного suffix | Принято `barkstock`, subtitle `Склад` |
| Charts/modals/fields | Правил не было | Добавлен `COMPONENT_RULES.md` |
| Loading | Spinner/skeleton/progress выбирались произвольно | Зафиксированы placement, timing и единый Bark loader |
| SSO login feedback | Кнопка могла оставаться без реакции до redirect | Обязательный spinner + `Входим…` удерживается до redirect/error |
| SSO employee photo | Можно было запрашивать отдельный API или менять Avatar | Зафиксирован прямой `picture`, CSP, URL lifecycle и fallback с инициалами |

## Ещё можно трактовать по-разному

1. Responsive sidebar: breakpoint, drawer width, overlay and swipe behavior.
2. Data tables: sticky header/columns и bulk actions (база, фильтры, пагинация,
   сортировка и row actions закреплены).
3. File upload: drop zone, retry and validation around the now-defined progress component.
4. Accessibility baseline: target WCAG level and test tooling.
5. Chart export/print behavior (библиотека выбрана).
6. Profile popover: состав (имя, роль, ссылки) и поведение — сейчас опционален.

Recommended next package: responsive sidebar (breakpoint + drawer) — последний
неспецифицированный кусок оболочки.