# Дизайн-система портфолио

Решения по дизайну сразу становятся работающими компонентами и повторно используемыми правилами

## Кратко о проекте

- **Проблема:** При быстрой разработке интерфейсов с агентами возникает дрейф, если исправления после review остаются единичными правками и не превращаются в многоразовые продуктовые правила.
- **Система:** Дизайн-система портфолио является repo-first операционным слоем, который хранит компоненты, токены, шаблоны страниц, контракты контента и инструкции для агентов рядом с работающим интерфейсом.
- **Входные данные:** Поведение работающего интерфейса, review владельца, повторяющиеся исправления, требования к Markdown-контенту и текущая реализация компонентов.
- **Результат:** Многоразовые компоненты, шаблоны страниц, токены и понятные агентам правила, улучшающие последующие изменения интерфейса.
- **Подтверждения:** Работающее Portfolio использует дизайн-систему версии 0.22.0 с общим пакетом, документационными маршрутами из реестра, превью компонентов, контрактами Essence, шаблонами страниц, адаптивными анимациями и паттерном Project About.
- **Статус:** Зрелая внутренняя система для одного публичного портфолио. Переиспользование в независимых продуктах и больших командах пока не проверено.

- **Полная история:** /ru/projects/portfolio-design-system/story/

## Полная история

Дизайн-система не начиналась как отдельный UI kit. Она выросла из практического следствия агентной разработки: сайт можно было менять быстро, но каждое быстрое локальное улучшение могло одновременно снижать целостность продукта.

Агент мог доработать одну карточку, решить одну проблему верстки или добавить одну страницу, не понимая решений, уже принятых в других местах. Компоненты постепенно получали пересекающиеся обязанности. Похожие поверхности расходились. Владельцу приходилось повторять одно и то же замечание, потому что предыдущая правка изменила страницу, но ничему не научила систему.

Дизайн-система Portfolio стала местом, где эти исправления накапливаются как продуктовая память.

## От исправления к многоразовому знанию

Каждое важное исправление после проверки работающего интерфейса оценивается как потенциально многоразовое знание и помещается на подходящий уровень.

Процесс начинается с выпущенного интерфейса, а не с абстрактного макета. Владелец проверяет, как читается реальная страница, где карточка перестает хорошо сканироваться, как шапка ведет себя на мобильном устройстве, не становится ли длинный текст слишком тяжелым и дает ли страница проекта достаточно контекста ИИ-агенту.

Сначала проблема исправляется в продукте. Затем определяется, какое решение представляет эта правка. Она может остаться локальной, стать публичным prop, перейти в родительский компонент, породить токен, изменить шаблон страницы или превратиться в общесистемное правило.

Если вывод может улучшить будущую работу, он переносится в дизайн-систему. Следующий агент получает не только исправленные пиксели, но и решение, стоящее за ними.

## Больше, чем визуальный каталог

Визуальное превью показывает внешний вид компонента, но не полностью объясняет его границы. Агентам также нужно знать, за что отвечает компонент, что должен передавать родитель, какие props являются публичными, какие состояния существуют только для документации и где должна заканчиваться композиция.

Так появились файлы Essence: короткие семантические документы, описывающие назначение, контракт, владение, крайние случаи и связи каждой значимой части системы. Они существуют рядом с реализацией и превью как руководство для людей и агентов.

`Page Template` является показательным примером. Он владеет общей оболочкой: Header, заменяемым контентом и Footer. Ему не нужно знать, является ли контент статьей, проектом или главной страницей. `Article Page`, `Project Landing Page`, `Project Story Page` и `Home Page` отвечают за соответствующие структуры контента.

Эта граница кажется небольшой, но не дает общему компоненту стать невидимым контроллером всего продукта. Дизайн-система фиксирует такие решения, потому что структурный дрейф обнаружить труднее, чем неверный цвет.

## Дизайн-система внутри продукта

Система находится в пакете `@portfolio/design-system` и используется самим публичным Portfolio. Документация доступна по адресу `/design-system/`, где у каждого элемента есть маршрут, запись в реестре, превью и Essence.

Это делает документацию операционной, а не декоративной. Компоненты проверяются в той же среде, где используются. Управление превью показывает поддерживаемые состояния, а реестр и файлы Essence дают агентам карту системы до начала изменений.

Позже документация была разделена на отдельные маршруты. Каждый маршрут загружает только свой документ и зависимости превью, а навигационная оболочка сохраняется между страницами. Поэтому каталог ведет себя как часть продукта, а не как большая внутренняя страница рядом с ним.

## Три связанных слоя

Дизайн-система Portfolio связывает три вида продуктового знания.

Визуальный слой определяет, как сайт читается и ведет себя: типографику, интервалы, цвет, интерактивные состояния, адаптивные ограничения, карточки, навигацию, длинный контент и движение.

Инженерный слой определяет композицию этого поведения: компоненты, props, границы владения, реестры, маршруты, шаблоны страниц и оболочки медиа.

Агентный слой объясняет, как будущие изменения должны сохранять эти решения. Файлы Essence, правила, превью, карты связей и журнал изменений под управлением Git позволяют агенту изучить существующую систему, а не угадывать ее по скриншоту.

Ценность появляется, когда эти слои остаются связанными. Визуальное решение без владельца реализации становится хрупким. Компонент без продуктового замысла легко использовать неправильно. Инструкции для агентов без работающего интерфейса превращаются в устаревшую документацию.

## Развитие вместе с работающим сайтом

Первый релиз создал локальный пакет и рабочий каталог компонентов. По мере роста Portfolio дизайн-система поглощала паттерны, нужные реальному контенту: карточки и макеты статей, страницы проектов, rich text, связанный контент, адаптивную навигацию, шаблоны страниц и публичные метаданные.

Более поздние релизы решали специфические потребности агентов. Передача Essence стала частью работы над компонентами. Agent Ready Project Brief добавил каждой странице проекта компактный блок контекста для людей и ИИ-систем. Публичная таксономия перешла от "use cases" к "projects", и это изменение прошло через компоненты, маршруты, документацию и редиректы совместимости, а не осталось простой правкой текста.

Визуалы проектов создали еще один многоразовый слой. SVG-сцены в реальном времени остаются исходником и fallback-вариантом, а общие медиа-оболочки доставляют адаптивные MP4 и WebM для мобильных, планшетных, настольных и сверхшироких экранов. Визуал одного проекта может расширить медиасистему, не заставляя каждую родительскую поверхность изучать его специфическое поведение.

К версии 0.22.0 система охватывала главную страницу, landing и story-страницы проектов, отображение текущего состояния проекта, заметки, макеты статей, карточки, rich text, навигационную оболочку, адаптивное поведение, документационные маршруты и анимации проектов.

## Текущая граница

Это рабочая дизайн-система одного публичного продукта. В ней есть общий пакет, история релизов в Git, документация на основе реестра, работающие превью, семантические Essence и прямое подтверждение в опубликованном интерфейсе.

Она еще не проверена как универсальная библиотека компонентов или инфраструктура для нескольких независимых команд. Продуктовые решения по-прежнему входят через review владельца, а система формируется потребностями этого Portfolio.

Эта граница намеренна. Система заслуживает абстракцию через повторное использование. Правило переносится на общий уровень, потому что работающему продукту оно понадобилось больше одного раза, а не потому, что полная дизайн-архитектура была придумана заранее.

В агентном процессе дизайн-система переносит решения вперед. Она не дает следующей реализации начинаться с пустого промпта и превращает повторяющиеся человеческие исправления в устойчивое поведение продукта.