diff --git a/development/design-system.md b/development/design-system.md index 0eda074..9459f32 100644 --- a/development/design-system.md +++ b/development/design-system.md @@ -2,24 +2,35 @@ Общий фундамент находится в [`frontend/src/shared/theme`](../../frontend/src/shared/theme/index.ts). -Его public API экспортирует `theme`, `cssVariablesResolver`, `colorRoles` и +Его public API экспортирует `theme`, `cssVariablesResolver`, `colorRoles`, `designTokens` и подключает базовые CSS. App владеет MantineProvider; Storybook подключает свой изолированный provider к тому же API. Тема и значения не копируются в preview. Оба runtime используют светлую схему; dark theme не заявлена как поддерживаемая. ## Тема и токены -[`theme.ts`](../../frontend/src/shared/theme/theme.ts) сохраняет фирменную синюю -палитру 0–9, системный sans-serif и default radius md. Именованные шкалы -fontSizes, fontWeights, lineHeights, headings, spacing, radius, shadows, -breakpoints и monospace явно принимаются из `DEFAULT_THEME` Mantine 9.5.1. -Числовой дубликат шкал не хранится. Font family заголовков совпадает с общей. +[`tokens.json`](../../frontend/src/shared/theme/tokens.json) — единственный +редактируемый источник опубликованных токенов WealthLedger. Он содержит восемь +палитр по десять оттенков: blue, gray, dark, red, green, yellow, grape и orange; +базовые white/black, оттенки по умолчанию, семантические роли с описаниями, +типографику, интервалы, радиусы, тени и breakpoints. Существующие значения +приняты из темы приложения и Mantine 9.5.1; теперь ими владеет JSON. Default +radius остаётся md, font family заголовков совпадает с общей. + +[`theme.ts`](../../frontend/src/shared/theme/theme.ts) проверяет source через +установленный Zod и [`tokens.schema.ts`](../../frontend/src/shared/theme/tokens.schema.ts), +затем адаптирует данные в Mantine. Схема проверяет структуру, единицы и диапазоны, +число оттенков и ссылки ролей; ошибочные данные не подменяются defaults. +Размеры px преобразуются native `rem`, сохраняя `--mantine-scale`, тени собираются +из слоёв с `rgba`, а breakpoints остаются em без масштабирования. Неопубликованные +палитры и настройки поведения компонентов остаются defaults Mantine. Используйте props Mantine (`gap="md"`, `p="xl"`, `radius="md"`, `shadow="xs"`) или `--mantine-spacing-*`, `--mantine-radius-*` и другие native CSS variables. [Foundations](http://localhost:6006/?path=/story/design-system-foundations--colors) -читает эффективную тему, показывает фактические значения и образцы. Обновление -Mantine требует повторной проверки шкал и внешнего вида приложения. +читает эффективную тему и описания из JSON, показывает фактические значения +и образцы. Обновление Mantine не заменяет принятые шкалы автоматически и требует +повторной проверки адаптера и внешнего вида приложения. `colorRoles` связывает смысл и native Mantine reference; resolver создаёт `--wl-color-`, ссылающийся на Mantine variable, без повторного hex-значения. @@ -42,13 +53,54 @@ Mantine требует повторной проверки шкал и внеш постепенного использования; существующие локальные Mantine references не переписаны массово. Цвет не заменяет подпись статуса. Палитра не гарантирует доступный контраст произвольных сочетаний: для текста и фона проверяйте контекст. -Grape остаётся дополнительной палитрой графиков; предметные значения задаёт Product. +Grape и orange используются Product; предметные значения задают их FSD-владельцы. Особые card gradients/shadows, размеры страницы и финансовые цвета CSS остаются у своих FSD-владельцев. Это сохранение существующего UI, а не завершённый редизайн или миграция всех literals в tokens. Новую общую шкалу стоит вводить только при реальном повторном использовании, если native Mantine scale не подходит. +## Переносимый JSON + +Файл использует собственный формат WealthLedger `formatVersion: 1`, без runtime +imports, CSS variables или исполняемого кода. Это контракт данных, а не заявление +о совместимости с DTCG или importer конкретной системы. + +| Данные | Представление | +| --- | --- | +| Цвета | Hex; palette — массив оттенков 0–9; base — именованные white/black. | +| Семантическая роль | `color`, `shade`, `description`; ссылка на palette или base. Для palette `shade: null` означает `primaryShade.light`, для base оттенок не нужен. | +| Типографика | CSS font stacks; размеры и headings в px, веса числовые, line heights без единиц. | +| Интервалы и радиусы | Именованные `values` xs–xl с `unit: "px"`; `radius.default` выбирает имя шкалы. | +| Тени | Упорядоченные слои: offsetX/offsetY/blur/spread в px, ссылка `color` на base и opacity 0–1. | +| Breakpoints | Именованные `values` xs–xl с `unit: "em"`, не зависят от масштаба UI. | + +Имена палитр `dimmed` и `bright` зарезервированы адаптером Mantine; +`white` и `black` принадлежат base colors. Вес шрифта ограничен диапазоном 1–1000. + +Внешний потребитель читает raw JSON напрямую. Например, из workspace root, +без Node, React или Mantine: + +```python +import json +from pathlib import Path + +tokens = json.loads(Path("frontend/src/shared/theme/tokens.json").read_text()) +assert tokens["formatVersion"] == 1 +colors = tokens["color"] +role = colors["roles"]["primary"] +shade = role["shade"] +if shade is None: + shade = colors["primaryShade"]["light"] +primary_hex = colors["palettes"][role["color"]][shade] +``` + +`shared/theme/index.ts` предназначен для frontend: он подключает CSS и Mantine +runtime. При интеграции с другой системой сопоставьте единицы, font stacks, +слои теней и semantic references с её форматом; парсер JSON сам этого не делает. +Несовместимое изменение требует новой версии контракта. Внешняя интеграция, +генератор артефактов и публикация пакета пока не реализованы. + ## Общие компоненты Public API — [`shared/ui`](../../frontend/src/shared/ui/index.ts). Минимальный diff --git a/development/ui-catalog.md b/development/ui-catalog.md index b393b27..5bbeaef 100644 --- a/development/ui-catalog.md +++ b/development/ui-catalog.md @@ -32,7 +32,7 @@ npm run preview:catalog | Блок / группа | Что показывает | | --- | --- | -| `Design System/Foundations` | Цвета и семантические роли, типографику, интервалы, радиусы, тени и breakpoints из действующей темы. | +| `Design System/Foundations` | Восемь палитр и семантические роли, типографику, интервалы, радиусы, тени и breakpoints из общей темы, адаптированной из tokens.json. | | `Design System/Components/StateView` | Четыре empty/error варианта с действием и без. | | `Design System/Components/LoadingSkeleton` | Общую доступную busy-область с нейтральными structural shapes. | | `Design System/Components/Button` | Прямой Mantine Button: primary, default, subtle, loading, disabled; локальное действие и keyboard interaction. | @@ -50,10 +50,11 @@ npm run preview:catalog Каталог не перечисляет весь Mantine или все компоненты приложения. AppShell с product navigation не объявлен компонентом общего набора. Отсутствие компонента -в каталоге не запрещает его использование. Foundations показывает используемые -шкалы, включая встроенные Mantine defaults; локальные размеры и особые тени -не объявляются глобальными токенами. [Дизайн-система](design-system.md) описывает -ownership и правила расширения. +в каталоге не запрещает его использование. Foundations показывает опубликованные +шкалы из `shared/theme/tokens.json`, описания ролей и эффективные Mantine значения. +Локальные размеры и особые тени не объявляются глобальными токенами; +неопубликованные defaults остаются у Mantine. [Дизайн-система](design-system.md) +описывает JSON-формат, внешнее чтение, ownership и правила расширения. Выберите историю в дереве, чтобы открыть её состояние в Canvas. Docs описывает назначение, ограничения и свойства группы, а также её примеры. Controls меняют @@ -71,7 +72,8 @@ Preview и приложение используют один public API `shared CSSVariablesResolver и базовые styles вместе с Mantine CSS. Preview использует русскую i18n и фиксированную светлую схему без чтения сохранённой темы. Stories находятся рядом с существующими presentation components и импортируют -их реализации. Токены и их семантические роли принадлежат shared/theme. Error StateView сохраняет alert semantics, +их реализации. Токены и описания их семантических ролей принадлежат +`shared/theme/tokens.json`; preview не хранит их копию. Error StateView сохраняет alert semantics, skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность действий и ссылок с клавиатуры вместе с визуальным состоянием.