# Визуальные принципы WealthLedger

Интерфейс использует общую визуальную основу на Mantine: цветовые роли,
типографику, интервалы, радиусы, тени и адаптивные размеры.
Поддерживается светлая схема; тёмная тема не заявлена.

## Общая основа и каталог

Внутри frontend используются три private npm workspace-пакета:

| Пакет | Ответственность |
| --- | --- |
| `@wealthledger/tokens` | JSON со значениями палитры, типографики, интервалов и других визуальных параметров |
| `@wealthledger/ui` | Mantine-тема, общие стили, StateView, LoadingSkeleton и EntryCard |
| `@wealthledger/icons` | React-иконки добавления, редактирования и удаления |

EntryCard отвечает за расположение переданных подписей, значения и действий.
Предметный компонент определяет смысл операции, форматирует данные и выбирает
цветовую роль. Денежные расчёты и запросы не входят в общий UI-пакет.

Иконки наследуют цвет через `currentColor`. По умолчанию они декоративные:
доступное имя принадлежит кнопке. Самостоятельная смысловая иконка получает
явные роль изображения и доступное имя. Предметные рисунки и анимации
остаются в приложении; поставки raw SVG и мобильного UI нет.

Storybook объединяет примеры приложения и пакетов. Он показывает синтетические
состояния без API, авторизации и query providers; формы получают локальные
callbacks. Каталог помогает проверять представление, но не заменяет проверки
запросов, денежных ограничений и восстановления после ошибок.

Пакеты используются локально и не опубликованы в registry. Независимый выпуск
не настроен. Потребители импортируют публичные exports пакетов напрямую; прежние
compatibility re-exports `shared/theme` и `shared/ui` удалены.

## Семантические роли

| Роль | Цветовая основа | Применение |
| --- | --- | --- |
| canvas | gray.2 | Фон приложения |
| surface | white | Поверхности и формы |
| subtle | gray.0 | Приглушённая поверхность |
| text | dark.7 | Основной текст |
| muted | gray.6 | Вторичный текст |
| border | gray.3 | Граница поверхности |
| primary | blue filled | Основное действие и активная навигация |
| info | blue.6 | Информация |
| positive | green.9 | Положительный результат с текстом или знаком |
| negative | red.9 | Ошибка или отрицательный результат с текстом или знаком |
| warning | yellow.6 | Предупреждение; не мелкий текст на белом |

Цвет не заменяет подпись или знак. Палитра не гарантирует доступный контраст
произвольного сочетания текста и фона. Дополнительные grape/orange и отдельные
оформления карточек сохраняют предметный смысл соответствующего экрана;
они не образуют универсальную финансовую классификацию всей системы.

## Состояния и действия

Основное, вторичное и вспомогательное действия различаются по визуальному
приоритету. Выполнение действия и его недоступность — разные состояния.
Пустой результат и ошибка содержат заголовок, пояснение и действие, когда
оно предусмотрено сценарием. Ошибка объявляется вспомогательным технологиям,
а кнопка имеет доступное название.

Первая загрузка показывает структуру ожидаемого содержимого, без вымышленных
сумм; область обозначается как занятая, декоративные фигуры не получают фокус.
Фоновое обновление сохраняет доступные данные с локальным индикатором.
Подробные правила — в [состояниях интерфейса](../architecture/cross-cutting/ui-resilience.md).

Финансовые значения сохраняют валюту (RUB), знак и различие между нулём и
неизвестной суммой. Предметные представления раскрыты в
[портфеле](../domains/portfolio/overview.md), [операциях](../domains/operations/overview.md)
и [банковских картах](../domains/cards/overview.md).

Согласованная общая основа описана в
[спецификации дизайн-системы](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/frontend-design-system/spec.md).