From f171b8bb4642dcaf0c9b4db8354eb6b8aaa4ea9d Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Tue, 8 Sep 2026 20:18:40 +0300 Subject: [PATCH] spec: simplify local design token validation contract --- .../.openspec.yaml | 2 + .../simplify-local-design-tokens/design.md | 75 +++++++++++++++++++ .../simplify-local-design-tokens/proposal.md | 31 ++++++++ .../specs/frontend-design-system/spec.md | 57 ++++++++++++++ .../simplify-local-design-tokens/tasks.md | 11 +++ 5 files changed, 176 insertions(+) create mode 100644 openspec/changes/simplify-local-design-tokens/.openspec.yaml create mode 100644 openspec/changes/simplify-local-design-tokens/design.md create mode 100644 openspec/changes/simplify-local-design-tokens/proposal.md create mode 100644 openspec/changes/simplify-local-design-tokens/specs/frontend-design-system/spec.md create mode 100644 openspec/changes/simplify-local-design-tokens/tasks.md diff --git a/openspec/changes/simplify-local-design-tokens/.openspec.yaml b/openspec/changes/simplify-local-design-tokens/.openspec.yaml new file mode 100644 index 0000000..7d363ac --- /dev/null +++ b/openspec/changes/simplify-local-design-tokens/.openspec.yaml @@ -0,0 +1,2 @@ +schema: wealth-ledger-sdd +created: 2026-09-08 diff --git a/openspec/changes/simplify-local-design-tokens/design.md b/openspec/changes/simplify-local-design-tokens/design.md new file mode 100644 index 0000000..d289125 --- /dev/null +++ b/openspec/changes/simplify-local-design-tokens/design.md @@ -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 | Прежние преобразования и обе сборки проходят проверки | diff --git a/openspec/changes/simplify-local-design-tokens/proposal.md b/openspec/changes/simplify-local-design-tokens/proposal.md new file mode 100644 index 0000000..b6c2005 --- /dev/null +++ b/openspec/changes/simplify-local-design-tokens/proposal.md @@ -0,0 +1,31 @@ +## Why + +Токены поставляются вместе с приложением и редактируются в репозитории. +Полная проверка произвольного входного документа добавила сложность, хотя +загрузка сторонних токенов не предусмотрена. Владелец согласовал её удаление. + +## What Changes + +Упростить потребление локальных токенов, сохранив переносимый источник, +единую тему и прежнее представление приложения и каталога. Убрать гарантию +runtime-отказа на произвольные некорректные токены; оставить проверки собственных +преобразований темы. Формат и значения токенов не меняются. + +Вне scope: внешняя загрузка токенов, редизайн, новые компоненты или зависимости, +продуктовые сценарии и изменение исторических архивов. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +- `frontend-design-system`: доверенный локальный источник вместо обязательной + runtime-валидации произвольных документов; остальные инварианты сохраняются. + +## Impact + +Затронуты общий frontend-фундамент, актуальная спецификация и документация. +Пользовательское поведение, API и данные остаются прежними. diff --git a/openspec/changes/simplify-local-design-tokens/specs/frontend-design-system/spec.md b/openspec/changes/simplify-local-design-tokens/specs/frontend-design-system/spec.md new file mode 100644 index 0000000..74d4e9f --- /dev/null +++ b/openspec/changes/simplify-local-design-tokens/specs/frontend-design-system/spec.md @@ -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 и проверке представления, автоматическое отклонение + любого некорректного документа не гарантируется + diff --git a/openspec/changes/simplify-local-design-tokens/tasks.md b/openspec/changes/simplify-local-design-tokens/tasks.md new file mode 100644 index 0000000..3a4ff2d --- /dev/null +++ b/openspec/changes/simplify-local-design-tokens/tasks.md @@ -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 и соответствие реализации.