# Как устроена спецификация «42»

Здесь видно, где хранится каждое решение, какие файлы собираются из него и что менять в разных задачах.

## Один источник для всех форматов

Каждое правило хранится в одном месте. HTML и Markdown собираются из общих данных и различаются только представлением.

- [/architecture](/architecture) — страница для чтения в браузере.
- [/architecture.md](/architecture.md) — полная Markdown-версия для ИИ-агента.

| Источник | Проекция | Потребитель |
| --- | --- | --- |
| `canon.js`, уровни композиции, компоненты, практики, паттерны и decisions | страницы, поиск, `spec.json`, llms и Markdown сущностей | дизайнер, разработчик, LLM |
| CSS-слои токенов | живой интерфейс, `tokens.json`, `scope.json`, контраст-тест | скины, аудит и внешние реализации |
| живые Svelte-демо | страницы компонентов и `examples.json` | человек и агент, которому нужен код |
| канон, токены и собранные машинные форматы | release bundle и удалённый Streamable HTTP MCP | агенты в продуктовых Vue- и Svelte-репозиториях |

В контракт попадают правила из данных канона и CSS-слоёв. HTML, JSON и Markdown собираются автоматически, поэтому отдельно их не редактируют.

## Источники истины

Источник истины хранит решение. Реестры и проекции только читают его.

| Сущность | Источник | Что в ней хранится |
| --- | --- | --- |
| Основания | `src/lib/spec/data/canon.js` | Манифест, принципы, оси, сквозные правила, сетка, движение и общие departures. |
| Юнит или компонент | `src/lib/spec/data/components/<id>.js` | `compositionLevel`, выбор сущности, ограничения, API, применимость взаимодействия, анатомия, состояния, клавиатура, доступность, departures и токен-контракт. |
| Уровни композиции | `src/lib/spec/data/composition-levels.js` | Критерии примитива, юнита, компонента и структуры, типы знания и фокус аудиторий. |
| Практика | `src/lib/spec/data/practices.js` | Сквозные нормативные правила: доступность, формы, контент и иконки. |
| Паттерн | `src/lib/spec/data/patterns.js` | Рецепт применения сущностей: связи, последовательность отклика, right/wrong-пара и скелет экрана. |
| Scope-решение и decision-scenario | `src/lib/spec/data/decisions.js` | Рубрика границы, вердикты по кандидатам и проверочные пары ожидаемого и запрещённого выбора. |
| Реестр | `src/lib/spec/data/registry.js` | Порядок опубликованных сущностей и список ещё не разобранных кандидатов. Самих правил и вердиктов здесь нет. |
| Скин | `src/lib/spec/skins.js` + `src/styles/skins/<id>.css` | Метаданные productScope и дельта значений поверх Blueprint. |
| Токены | `src/styles/` | Значения дизайна: канонные шкалы, смысловые роли, полный компонентный контракт Blueprint и брендовые дельты. |
| Пример | `src/routes/<id>/demos/*.svelte` + `examples[]` компонента | Живое поведение и исходный код примера без ручной JSON-копии. |

`docs/spec.schema.json` описывает структуру канона. `releases.js` хранит историю, из которой собираются `/changes.json` и `/spec-changelog.md`. Consumer и lock задают внешний протокол. `lib/mcp` читает готовые проекции.

## Уровни композиции и типы знания

Уровень показывает, из скольких частей собрана сущность. Тип знания описывает способ её применения.

- `primitive` - визуальное основание без собственной пользовательской задачи.
- `unit` - одно действие, значение или состояние.
- `component` - несколько юнитов решают одну локальную задачу.
- `structure` - компоненты образуют сценарий или каркас экрана.
- `pattern` - рецепт применения сущностей любого уровня. Это тип знания, а не пятый уровень.

Нормативные правила хранятся в `guidelines` с уровнями `must`, `must-not` и `should`. Поле `useCases` помогает выбрать сущность. Дублировать правила в `doDont`, `agentRules` или Markdown нельзя.

## Что получает человек

На сайте можно сравнить решения, проверить поведение и прочитать полный канон.

- [/](/) — маршруты для менеджера, дизайнера и разработчика.
- [/overview](/overview) — принципы, уровни композиции и список сущностей.
- [/<component>](/button) — живые демо и полные правила компонента.
- [/accessibility, /forms, /content, /icons](/accessibility) — сквозные практики.
- [/patterns/<id>](/patterns/form) — паттерны и композиционные примеры.
- [/decisions](/decisions) — критерии границы, принятые решения и проверочные сценарии для ИИ.
- [/skins](/skins) — один набор живых компонентов во всех скинах.
- [/scope](/scope) — покрытие юнитов и компонентов скинами.
- [/palette, /typography, /spacing, /radii-shadows](/palette) — живые витрины токенов.

`SpecRules.svelte` строит правила, `AnatomyDiagram.svelte` показывает анатомию, а `StateDiagram.svelte` карту состояний. Практики и паттерны используют общие шаблоны страниц.

## Что получает ИИ-агент

Агент сначала читает `/agents.md` и `/release.json`, затем выбирает формат под задачу. Правила берутся из машинных данных, а не извлекаются из HTML.

1. `/release.json` - текущая версия и ревизии артефактов и сущностей
2. `/changes.json` - изменения между версиями
3. `/spec.json` - нормативный контракт `42-spec/7`
4. `/examples.json` - код живых примеров
5. `/tokens.json` - CSS-токены в формате DTCG
6. `/scope.json` - покрытие юнитов и компонентов скинами
7. `/<id>.md` - компактный Markdown одной сущности

- `/llms.txt` - индекс и маршрутизация
- `/llms-full.txt` - весь канон и эта архитектурная карта одним текстом
- `/decisions.md` - решения о составе и проверочные сценарии
- `/token-usage.json` - обратный индекс потребителей каждого токена
- `/spec.schema.json` - JSON Schema формата
- `/spec-changelog.md` - история версий для чтения человеком
- `/consumer.schema.json` - контракт локального consumer manifest
- `/lock.schema.json` - контракт локального lock-файла

Все страницы и файлы сайта пререндерятся через `adapter-static`. Runtime API у сайта нет. Удалённый Streamable HTTP MCP работает отдельным процессом и только читает ту же сборку. Эта страница целиком входит в `/architecture.md` и `/llms-full.txt`.

## Удалённый MCP

Streamable HTTP MCP запускается отдельным Node-процессом по `/mcp`. Он читает текущий `build/`, поэтому статические URL и MCP отдают одну версию и ревизии.

- Ресурсы `ds42://release/current`, `ds42://changes`, `ds42://spec/current`, `ds42://tokens/current` и consumer-схемы дают постоянные точки чтения.
- Шаблоны `ds42://component/{id}`, `ds42://practice/{id}`, `ds42://pattern/{id}` и `ds42://examples/svelte/{id}` открывают одну сущность.
- `search_canon` ищет по нормативным данным, `diff_releases` строит миграцию между версиями.
- `get_implementation_task` собирает компонент, примеры, токены и изменения; `validate_consumer` проверяет manifest/lock.

MCP не получает доступ к продуктовому репозиторию. Агент читает канон удалённо, а локальные файлы и тесты остаются в его среде. Если MCP недоступен, те же данные можно прочитать по статическим URL.

## Скины и токены

Blueprint задаёт полный каркас в `skin-defaults.css`. Бренд-скин меняет только компонентные токены. Сетка `--sp-*` остаётся общей.

Состав свойств компонента задаётся его `tokens[]` в каноне. Значения меняются непосредственно в соответствующем CSS-слое, а бренд-скин хранит только дельту поверх полного контракта Blueprint.

Шкалы живут в `base.css`, семантические роли — в `semantic.css`, полный компонентный контракт — в `skin-defaults.css`, брендовые дельты — в `skins/*.css`. Примитивы обновляются через `scripts/palette/source.json` и общий генератор.

1. Создайте дельту в `src/styles/skins/<id>.css`.
2. Импортируйте её после Blueprint в `src/app.css`.
3. Добавьте `summary` и `source` в `src/lib/spec/skins.js`.
4. Проверьте скин в селекте, на `/skins`, в `/scope.json` и DTCG.
5. Запустите `skin-contract.test.js` и `contrast-contract.test.js`.

Новый компонентный токен сначала появляется в Blueprint. Скин может только переопределить его значение.

## Версии контракта

Версия канона и версии форматов меняются независимо. Канон описывает смысл, формат описывает структуру файла.

- `canon.version` записывается в `/spec.json.meta.version` и обозначает версию канона.
- `/spec.json.format` и поля format в других JSON обозначают версию структуры файла.
- `/release.json` связывает версию канона с SHA-256-ревизиями артефактов и сущностей.

Редакционная правка не меняет версию канона. Новое правило или ломающее изменение требует записи в истории и новой `canon.version`. При изменении поля обновляются формат, схема, тесты и рецепты.

`deprecated` требует `deprecation.replacement` и `deprecation.migration`. Потребитель фиксирует версию и ревизии в `42.lock.json`, чтобы отличить затронутые сущности от неизменившихся.

## Как вносить изменения

Сначала измените источник решения. Проекции обновятся автоматически.

| Задача | Что менять | Что обновится автоматически |
| --- | --- | --- |
| Правило, пропс, состояние или анатомия компонента | Data-модуль компонента. `lib/ui` меняется только вместе с поведением | Страница правил, поиск, `spec.json`, llms и `/<id>.md` |
| Сквозная практика | `practices.js` | Страница практики, поиск и машинные форматы |
| Паттерн применения | `patterns.js` | `/patterns/<id>`, поиск и машинные форматы |
| Scope-вердикт или decision-scenario | `decisions.js` | `/decisions`, поиск, `spec.json`, `/decisions.md` и llms |
| Живой пример | `examples[]` компонента и соответствующий demo-файл | Страница компонента и `/examples.json` |
| Значение токена или дельта скина | Нужный CSS-слой. Примитив меняется через локальный источник палитры | Витрины, DTCG и вычисляемый scope |
| Новый скин | CSS-дельта, импорт и `skins.js` | Селект, галерея, scope и машинная спека |
| Новое поле или ломающее изменение | Данные, `spec-object.js`, JSON Schema, `releases.js`, тесты и рецепт | Пререндеренный контракт, release и MCP после сборки |

Для типовых изменений используйте рецепты из `.claude/skills/`.

- `add-component/SKILL.md` - новый компонент.
- `edit-canon/SKILL.md` - правила и тексты канона.
- `add-skin/SKILL.md` - новый или изменённый бренд-скин.
- `tokens-work/SKILL.md` - токены, палитра и генератор.
- `verify-ds/SKILL.md` - гейты и функциональная проверка.

## Внешние потребители

Внешний продукт читает машинные форматы и связывает локальные компоненты с canonical id. Реализация остаётся в продуктовом репозитории и не публикуется в «42».

- Описать покрытие в `42.consumer.json`: framework, canonical id, локальные пути и статус реализации.
- Зафиксировать версию и ревизии из `/release.json` в `42.lock.json`.
- При новой версии читать `/changes.json` только для canonical id из manifest и сравнивать их ревизии.
- Описать переименованные и намеренно не реализованные пропсы в `propMap` и `coverage`.
- Документировать каждое осознанное отступление от канона рядом с адаптером.
- Обновлять реализацию и lock у себя; не регистрировать её как публичный скин «42».

Неполное покрытие допустимо, если оно отмечено предупреждением. Неописанное расхождение имён, пропсов или правил завершает проверку ошибкой.

## Гейты

Перед завершением содержательной правки запустите эти команды.

- `pnpm test`
- `pnpm build`
- `pnpm lint`
- `pnpm check:types` при изменении JS-сигнатур

В `ds` consumer-протокол проверяют нейтральные Vue и Svelte фикстуры. Совместимость конкретного продукта проверяется в его репозитории. Оператор сравнивает скин с макетом, а тесты проверяют структуру, токены, контраст и расхождения.

## Что не документировать отдельно

- Правила компонентов в отдельном Markdown.
- Вторую агентскую версию `guidelines`.
- Ручную таблицу scope.
- Копию токенов вне CSS.
- Копию примеров вне demo-файлов.
- Запланированные сущности как будто они уже реализованы.

Новое пояснение добавляется в общий источник. После сборки его получают сайт и ИИ-агент.