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