spec: define portable design token source
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
## Context
|
||||
|
||||
Текущий shared/theme задаёт blue, font family и colorRoles в TypeScript;
|
||||
остальные опубликованные шкалы получает из DEFAULT_THEME Mantine 9.5.1.
|
||||
Приложение и Storybook уже используют один provider contract; 9 групп / 30
|
||||
stories существуют. Переносимость требует источника, который читается обычным
|
||||
JSON parser без runtime этих библиотек.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:** JSON ownership общих токенов и semantic descriptions, узкий Mantine
|
||||
adapter, валидация source contract, прежние эффективные размеры/цвета/поведение.
|
||||
|
||||
**Non-Goals:** новый token engine, внешние integrations или публикация пакета,
|
||||
автоматическая совместимость с DTCG импортерами, dark theme, новые компоненты,
|
||||
редизайн, перенос локальных product literals, изменение API/backend и архивов.
|
||||
|
||||
## Decisions
|
||||
|
||||
- `shared/theme/tokens.json` — единственный редактируемый источник опубликованных
|
||||
токенов: formatVersion, description, palette/base colors, default shades,
|
||||
semantic roles с description, typography, spacing/radius, shadows, breakpoints.
|
||||
JSON самодостаточен: нет DEFAULT_THEME imports, CSS variables и executable code.
|
||||
- Формат WealthLedger v1 документируется явно. Hex colors, числовые weights и
|
||||
unitless line heights, размерные группы с unit px, breakpoints с unit em;
|
||||
shadow состоит из упорядоченных слоёв offsetX/offsetY/blur/spread в px,
|
||||
color и opacity. Font families — строки CSS font stacks. Semantic role
|
||||
ссылается на palette/base color по имени и optional shade; null shade палитры
|
||||
означает primaryShade.light для поддерживаемой светлой схемы. Base colors
|
||||
используют null shade. Описания ролей также принадлежат JSON.
|
||||
- В source закрепляются blue, gray, dark, red, green, yellow, grape и orange
|
||||
(используется Product), white/black, все опубликованные typography/layout scales.
|
||||
Их текущие значения принимаются один раз из baseline. Необъявленные Mantine
|
||||
palettes и UI behavior defaults остаются библиотечными и не считаются токенами
|
||||
переносимого контракта. JSON не генерируется обратно из Mantine.
|
||||
- `theme.ts` адаптирует проверенные данные: native rem(px) сохраняет scale,
|
||||
breakpoints преобразуются в em без scale, shadows — в CSS с теми же слоями.
|
||||
Primary role сохраняет native filled reference; resolver выдаёт прежние
|
||||
--wl-color-* aliases. App/preview, shared styles и компоненты не меняются.
|
||||
- Установленный Zod валидирует shape, units/ranges, palette cardinality и role
|
||||
references при чтении source; некорректные tokens не получают fallback.
|
||||
Это ограниченная схема текущего формата, без цепочек aliases, resolver graph,
|
||||
plugin architecture или динамической загрузки внешних tokens.
|
||||
- Foundations читает effective theme и JSON descriptions; показывает источник
|
||||
и границу portable contract, сохраняя story IDs и оба блока. Frontend импортирует
|
||||
theme/tokens через public API; внешний потребитель читает raw JSON напрямую,
|
||||
не исполняя barrel с CSS и Mantine.
|
||||
|
||||
## UI/UX Applicability and Package
|
||||
|
||||
**Applicability and scope:** new/changed только для пояснений Foundations и
|
||||
добавления уже используемой orange palette в обзор. Приложение, общие компоненты,
|
||||
Product states/interactions и responsive поведение сохраняются без нового макета.
|
||||
|
||||
**Package revision:** 1, полностью inline Markdown, exports не нужны.
|
||||
|
||||
**Screens, states and interactions:** Colors содержит те же semantic role cards,
|
||||
данные/описания из JSON и palette swatches, включая orange. Typography и Layout
|
||||
сохраняют образцы, поясняют JSON ownership вместо DEFAULT_THEME ownership.
|
||||
Button, StateView, LoadingSkeleton и Product используют прежние реализации.
|
||||
|
||||
**Responsive behavior:** существующие grids/stack сохраняются; длинные source
|
||||
пояснения переносятся на 375px. Изменение Mantine scale продолжает масштабировать
|
||||
spacing/radius/type/shadow dimensions; responsive thresholds остаются em.
|
||||
|
||||
**Reused source and differences:** implementation baseline; historical Design
|
||||
package не переиспользуется как external authority, archived artifacts не меняются.
|
||||
|
||||
## Delivery Map
|
||||
|
||||
| Area | Status | Architectural outcome or N/A reason |
|
||||
| --- | --- | --- |
|
||||
| frontend | affected | Самодостаточный tokens.json, schema и Mantine adapter, актуальный Foundations |
|
||||
| backend | N/A | API/auth/storage и денежные вычисления не затронуты |
|
||||
| specs | affected | Уточнённый source/ownership contract и фактическое evidence |
|
||||
| docs | affected | As-built JSON format, ownership, usage и integration limits |
|
||||
|
||||
### Contract Gate Decision
|
||||
|
||||
| Gate | Status | Reason |
|
||||
| --- | --- | --- |
|
||||
| runtime-openapi | N/A | Frontend/backend API contract не меняется |
|
||||
|
||||
## Solution Assessment
|
||||
|
||||
Обычный JSON читается стандартными парсерами без operating dependencies;
|
||||
Mantine rem/createTheme/getThemeColor и установленный Zod покрывают adaptation
|
||||
и validation. Полный DTCG или Style Dictionary уместен при выбранном потребителе
|
||||
и требованиях к transforms, но сейчас добавляет форматные преобразования и
|
||||
tooling без подтверждённой совместимости целевого инструмента. Собственный
|
||||
контракт ограничен данными и прямым adapter, без универсального движка. При
|
||||
выборе внешнего потребителя оценить его importer и трансформацию в требуемый формат.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- JSON теперь владеет принятыми шкалами: обновление Mantine не заменяет их
|
||||
автоматически; локальные library defaults вне portable contract могут измениться.
|
||||
- Числовые px в adapter используют rem, а не простые rem strings, чтобы сохранить
|
||||
--mantine-scale. Breakpoints не масштабируются. Structured shadows могут дать
|
||||
другой строковый порядок CSS при одинаковом computed value.
|
||||
- Публичный format v1 требует явного изменения контракта при несовместимом изменении;
|
||||
существующая browser интеграция не доказывает импорт конкретным внешним инструментом.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Сохранить baseline; перенести данные в JSON, включить schema и adapter; обновить
|
||||
Foundations и документацию. Выполнить checks и независимый read-only review,
|
||||
затем canonical completion. Прямое разрешение владельца в беседе сохраняет
|
||||
workflow без session records и повторных промежуточных approval stops.
|
||||
|
||||
### Rollback Contract
|
||||
|
||||
| Field | Decision |
|
||||
| --- | --- |
|
||||
| Status | required |
|
||||
| Trigger | Нарушено представление или потребление нового source contract |
|
||||
| Actions | Вернуть delivery diff frontend/docs и соответствующую spec delta; не править исторические архивы. При появлении реального внешнего потребителя сохранить v1 JSON до его согласованной миграции. |
|
||||
| Data safety | User data/auth не меняются; экспортированный v1 источник сохраняется для уже подключённых потребителей |
|
||||
| Verification | Прежняя тема и обе сборки проходят gates; browser образцы совпадают с baseline |
|
||||
Reference in New Issue
Block a user