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

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

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

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

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

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

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

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 - принципы, уровни композиции и список сущностей
• /<component> - живые демо и полные правила компонента
• /accessibility, /forms, /content, /icons - сквозные практики
• /patterns/<id> - паттерны и композиционные примеры
• /decisions - критерии границы, принятые решения и проверочные сценарии для ИИ
• /skins - один набор живых компонентов во всех скинах
• /scope - покрытие юнитов и компонентов скинами
• /palette, /typography, /spacing, /radii-shadows - живые витрины токенов

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, чтобы отличить затронутые сущности от неизменившихся.

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

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

Для типовых изменений используйте рецепты из .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-файлов.
• Запланированные сущности как будто они уже реализованы.

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