spec: simplify local design token validation contract
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: wealth-ledger-sdd
|
||||
created: 2026-09-08
|
||||
@@ -0,0 +1,75 @@
|
||||
## Context
|
||||
|
||||
JSON v1 хранится в shared/theme и импортируется при сборке. Zod-схема и
|
||||
большая часть token tests обслуживают неподдерживаемый сценарий произвольного
|
||||
входного документа. App/Storybook уже используют общий public API.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:** прямое потребление локального JSON, сохранение адаптации и визуальных
|
||||
значений, небольшой тест собственных преобразований.
|
||||
|
||||
**Non-Goals:** замена runtime-схемы новой системой типов или генератором,
|
||||
изменение JSON/компонентов/провайдеров, удаление Zod из бизнес-форм,
|
||||
внешняя загрузка токенов, редизайн и новые зависимости.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Удалить tokens.schema.ts и связанные negative/document-shape tests.
|
||||
theme.ts напрямую импортирует tokens.json, сохраняет public exports и
|
||||
Mantine rem/rgba/getThemeColor adaptation.
|
||||
- Использовать вывод типов JSON и существующие типы/helpers Mantine там,
|
||||
где JSON расширяет литералы; не создавать параллельное полное описание
|
||||
token contract. Type assertions при необходимости ограничены границей
|
||||
адаптера и не считаются validation.
|
||||
- Два кратких theme.test.ts сценария защищают собственные преобразования:
|
||||
scale-aware размеры/тени и unscaled breakpoints; semantic color references.
|
||||
Это оставшаяся полезная часть текущих тестов, без тестирования схемы.
|
||||
- Формат JSON и правила редактирования сохраняются в as-built docs. Корректность
|
||||
локальных изменений проверяется обычными repository gates, review и UI proof;
|
||||
полный автоматический отказ для произвольного invalid JSON больше не обещается.
|
||||
|
||||
## UI/UX Applicability and Package
|
||||
|
||||
**Applicability and scope:** N/A: значения, стили, экраны, states, interactions
|
||||
и responsive behavior не меняются; удаляется только runtime-проверка конфигурации.
|
||||
Новый визуальный пакет не требуется.
|
||||
|
||||
## Delivery Map
|
||||
|
||||
| Area | Status | Architectural outcome or N/A reason |
|
||||
| --- | --- | --- |
|
||||
| frontend | affected | Прямой JSON adapter, компактный theme test и ownership docs |
|
||||
| backend | N/A | API/auth/storage и денежная логика не затронуты |
|
||||
| specs | affected | Уточнён контракт доверенного локального источника |
|
||||
| docs | affected | As-built описание прямого адаптера и границ проверки |
|
||||
|
||||
### Contract Gate Decision
|
||||
|
||||
| Gate | Status | Reason |
|
||||
| --- | --- | --- |
|
||||
| runtime-openapi | N/A | Ни одна сторона API contract не меняется |
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
Произвольное некорректное значение не обязано вызывать раннюю ошибку загрузки.
|
||||
Это согласованное упрощение для конфигурации репозитория, а не снятие проверки
|
||||
на границе внешних данных: такого входа здесь нет. Если появится внешняя загрузка,
|
||||
её trust boundary и validation должны проектироваться отдельно.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
Сохранить baseline преобразований; удалить схему и её тесты, подключить JSON
|
||||
напрямую; актуализировать документацию и проверить неизменность темы.
|
||||
Прямое разрешение владельца распространяется на planning и delivery без
|
||||
session records и повторных промежуточных approvals.
|
||||
|
||||
### Rollback Contract
|
||||
|
||||
| Field | Decision |
|
||||
| --- | --- |
|
||||
| Status | required |
|
||||
| Trigger | Адаптер меняет представление либо потребителю необходим прежний runtime-отказ |
|
||||
| Actions | Вернуть delivery diff и согласовать обратную spec delta; historical archives не менять |
|
||||
| Data safety | JSON v1 и пользовательские данные остаются прежними |
|
||||
| Verification | Прежние преобразования и обе сборки проходят проверки |
|
||||
@@ -0,0 +1,31 @@
|
||||
## Why
|
||||
|
||||
Токены поставляются вместе с приложением и редактируются в репозитории.
|
||||
Полная проверка произвольного входного документа добавила сложность, хотя
|
||||
загрузка сторонних токенов не предусмотрена. Владелец согласовал её удаление.
|
||||
|
||||
## What Changes
|
||||
|
||||
Упростить потребление локальных токенов, сохранив переносимый источник,
|
||||
единую тему и прежнее представление приложения и каталога. Убрать гарантию
|
||||
runtime-отказа на произвольные некорректные токены; оставить проверки собственных
|
||||
преобразований темы. Формат и значения токенов не меняются.
|
||||
|
||||
Вне scope: внешняя загрузка токенов, редизайн, новые компоненты или зависимости,
|
||||
продуктовые сценарии и изменение исторических архивов.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
Нет.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `frontend-design-system`: доверенный локальный источник вместо обязательной
|
||||
runtime-валидации произвольных документов; остальные инварианты сохраняются.
|
||||
|
||||
## Impact
|
||||
|
||||
Затронуты общий frontend-фундамент, актуальная спецификация и документация.
|
||||
Пользовательское поведение, API и данные остаются прежними.
|
||||
@@ -0,0 +1,57 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Приложение и каталог используют единый визуальный фундамент
|
||||
|
||||
Приложение и каталог SHALL использовать один источник темы и токенов: цвета
|
||||
с семантическими ролями, типографику, интервалы, радиусы, тени и применимые
|
||||
адаптивные параметры. Общий фундамент MUST быть независим от бизнес-сущностей
|
||||
и уровня приложения; подключение провайдеров принадлежит приложению и runtime
|
||||
каталога. Объявленные общие токены SHALL иметь единый переносимый машиночитаемый
|
||||
источник значений, единиц, семантических ссылок и описаний, доступный без
|
||||
приложения или UI-библиотеки. Адаптер приложения SHALL потреблять этот источник
|
||||
без ручного дублирования значений. Перенос владения опубликованными шкалами
|
||||
из UI-библиотеки в токены MUST сохранять их эффективные значения; не включённые
|
||||
в контракт библиотечные defaults MAY оставаться у библиотеки. Выделение фундамента MUST сохранять текущий
|
||||
внешний вид, светлую схему и поведение приложения без массовой замены локальных
|
||||
значений оформления. Источник SHALL поставляться вместе с приложением как
|
||||
доверенная конфигурация; загрузка внешних или пользовательских токенов
|
||||
и отдельная runtime-валидация произвольных документов не поддерживаются.
|
||||
|
||||
#### Scenario: Компонент отображается в приложении и каталоге
|
||||
|
||||
- **WHEN** один компонент с одинаковыми props отображается в обоих runtime
|
||||
- **THEN** он получает одинаковые тему, токены и общие визуальные правила
|
||||
|
||||
#### Scenario: Участник выбирает токен
|
||||
|
||||
- **WHEN** участник изучает фундамент дизайн-системы
|
||||
- **THEN** доступны используемые шкалы, их значения, семантические роли и правила
|
||||
применения без необходимости обращаться к данным приложения
|
||||
|
||||
#### Scenario: Владение темой перенесено
|
||||
|
||||
- **WHEN** приложение использует выделенный общий фундамент
|
||||
- **THEN** исходные эффективные значения и внешний вид остаются прежними,
|
||||
включая встроенные шкалы, глобальные стили и локальное оформление
|
||||
|
||||
#### Scenario: Токены использует другая система
|
||||
|
||||
- **WHEN** потребитель читает исходный файл обычным парсером данных
|
||||
- **THEN** объявленные цвета, роли, типографика, интервалы, радиусы, тени и
|
||||
адаптивные пороги доступны с определёнными единицами и ссылками без React,
|
||||
Mantine, CSS runtime или запуска приложения; интеграция конкретного инструмента
|
||||
не заявляется автоматически
|
||||
|
||||
#### Scenario: Изменён исходный токен
|
||||
|
||||
- **WHEN** валидное значение или семантическая ссылка изменены в едином источнике
|
||||
- **THEN** приложение и каталог получают изменение через один адаптер, без
|
||||
повторного редактирования визуального значения в коде темы
|
||||
|
||||
#### Scenario: Исходные токены некорректны
|
||||
|
||||
- **WHEN** разработчик вносит некорректное значение в локальный источник
|
||||
- **THEN** отдельный runtime-валидатор не применяется; корректность изменения
|
||||
проверяется при review и проверке представления, автоматическое отклонение
|
||||
любого некорректного документа не гарантируется
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
## 1. Упрощение локальных токенов
|
||||
|
||||
- [x] 1.1 [frontend] Удалить runtime-схему и её тесты, подключить JSON напрямую, оставить два теста адаптера и актуализировать ownership docs.
|
||||
- **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент`
|
||||
- **Verification:** npm ci и npm run verify под .nvmrc; baseline/after theme и browser smoke Design System/Product/login; JSON values и provider contract неизменны.
|
||||
- [x] 1.2 [specs] Оформить согласованный контракт доверенного источника и planning без изменения historical archives/state.
|
||||
- **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент`
|
||||
- **Verification:** openspec schema validate wealth-ledger-sdd --verbose; openspec validate simplify-local-design-tokens --type change --strict --store wealth-ledger-specs; openspec validate --specs --strict --store wealth-ledger-specs; semantic sync review.
|
||||
- [x] 1.3 [docs] Описать прямое потребление локального JSON и фактические границы проверки.
|
||||
- **Covers:** `frontend-design-system` — `Приложение и каталог используют единый визуальный фундамент`
|
||||
- **Verification:** npm ci и npm run verify под docs .nvmrc; affected local links и соответствие реализации.
|
||||
Reference in New Issue
Block a user