spec: simplify local design token validation contract

2026-09-08 20:18:40 +03:00
parent ca709b5ab9
commit f171b8bb46
5 changed files with 176 additions and 0 deletions
@@ -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 | Прежние преобразования и обе сборки проходят проверки |