Storybook Codex

storybook-codex — это plugin-ready Codex-пакет для работы со Storybook.

Storybook — инструмент разработчика для создания галереи UI-компонентов и их состояний, чтобы команды могли просматривать кнопки, диалоги и формы без запуска полного приложения. Storybook Codex помогает Codex создавать, обновлять, документировать и ревьюить Storybook-примеры по всему репозиторию.

Zero-build демо, циклически проходящее по шести фикстурам репозитория. Каждая карточка — именованный экспорт Story, отрендеренный со своими args. Запустите python demo/build.py && python -m http.server 8765 --directory demo для локального запуска.

Скилл даёт Codex один сфокусированный навык, который умеет:

• создавать и обновлять Storybook-истории для React, Vue и Svelte
• генерировать отдельные страницы документации в .stories.mdx
• генерировать CSF-истории с тегом docs и parameters.docs.description
• предлагать истории родительского контекста на основе реального использования компонентов
• обновлять только затронутые истории по сигналам git diff
• генерировать preview-декораторы Storybook из провайдеров приложения
• генерировать args, выборочные argTypes, controls и теги autodocs
• создавать interaction-истории с play() и storybook/test
• предлагать истории доступности вместо того, чтобы откладывать a11y на потом
• подключать хуки визуальной регрессии для Chromatic или локального Playwright-окружения
• обнаруживать дизайн-токены и выставлять глобальные переменные темы или плотности
• ревьюить существующие истории и оценивать здоровье Storybook по всему репозиторию
• синхронизировать структуру историй между фреймворками

Что делает этот скилл полезным

Большинство Storybook-промптов останавливаются на «создай файл с историей». Этот скилл идёт дальше:

• story_blueprint.py учитывает контекст репозитория, а не только пропсы. Он анализирует использование, совместную встречаемость, ветвящиеся пропсы, interaction-потоки, a11y-линзы и визуальные базовые линии.
• story_docs.py превращает API компонентов и реальное использование в практичные страницы документации или истории с тегом docs, а не оставляет документацию на откуп ручному тексту.
• story_composition.py находит родительские контексты, в которых компоненты реально используются, и превращает их в предложения для wrapper-историй.
• story_diff_update.py читает вывод git diff и обновляет только те истории, которые были затронуты изменением API компонента.
• storybook_decorators.py инспектирует провайдеры приложения и генерирует preview-декораторы или Vue setup-хуки, избавляя команды от необходимости писать их вручную снова.
• storybook_audit.py превращает скилл в постоянную систему контроля качества с оценкой Story Health Score.
• story_sync.py поддерживает согласованность структур историй для React, Vue и Svelte в мультифреймворковых дизайн-системах.
• token_catalog.py находит CSS-переменные и токены в стиле Tailwind и предлагает глобальные переменные Storybook для темы и плотности.
• tools/fixtures-viewer/ делает контракт валидации доступным для просмотра, а не зарытым в JSON.

Что входит в поставку

• .codex-plugin/plugin.json для plugin-упаковки
• skills/storybook-codex/ с самим Codex-скиллом
• skills/storybook-codex/scripts/story_blueprint.py для blueprinting, режима ревью и режима watch
• skills/storybook-codex/scripts/story_docs.py для генерации в режиме docs
• skills/storybook-codex/scripts/story_composition.py для обнаружения историй родительского контекста
• skills/storybook-codex/scripts/story_diff_update.py для change-aware обслуживания историй по git diff
• skills/storybook-codex/scripts/storybook_decorators.py для создания .storybook/preview из деревьев провайдеров
• skills/storybook-codex/scripts/storybook_audit.py для оценки Storybook по всему репозиторию
• skills/storybook-codex/scripts/story_sync.py для синхронизации историй между фреймворками
• skills/storybook-codex/scripts/token_catalog.py для глобальных переменных с учётом токенов
• skills/storybook-codex/references/ с правилами для фреймворков, режимом docs, visual diff, interaction, a11y, токенами, аудитом и руководством по Storybook 9
• skills/storybook-codex/assets/templates/ со стандартными историями, docs-историями, interaction-историями, спецификациями визуальной регрессии, конфигурацией token preview и стартерами для конкретных библиотек
• fixtures/cases.json как машиночитаемый контракт валидации
• fixtures/docs-sample/ как примеры фикстур для режима docs
• tools/fixtures-viewer/ как UI для просмотра этого контракта
• scripts/validate_storybook_codex.py для валидации без зависимостей

Основные рабочие процессы

Blueprint компонента

Полезные флаги:

• --repo-root <path> для анализа использования в локальном приложении
• --review-story path/to/Component.stories.tsx для критики существующего файла с историями
• --watch для повторного запуска blueprint при изменении компонента

Генерация документационных историй

python3 skills/storybook-codex/scripts/story_docs.py path/to/Component.tsx --style csf

или:

python3 skills/storybook-codex/scripts/story_docs.py path/to/Component.tsx --style mdx

Используйте это, когда autodocs слишком скуден и компоненту нужны:

• описание назначения и антипаттернов
• руководство по выбору пропсов
• два-три примера типичного использования
• CSF-история с тегом docs или отдельная страница .stories.mdx

Предложение composition-историй

python3 skills/storybook-codex/scripts/story_composition.py path/to/Component.tsx --repo-root path/to/repo

Используйте это, когда компонент имеет смысл только внутри формы, сетки, карточки, диалога или боковой панели.

Обновление историй по git diff

Используйте --diff-file в CI или при валидации, когда нужно, чтобы обновлятор читал сохранённый патч вместо живого diff репозитория.

Генерация preview-декораторов

python3 skills/storybook-codex/scripts/storybook_decorators.py path/to/repo --framework react --format preview

Эта команда инспектирует App.tsx, main.tsx или main.ts и генерирует дерево провайдеров, необходимое Storybook.

Аудит Storybook-репозитория

python3 skills/storybook-codex/scripts/storybook_audit.py path/to/repo --format markdown

Используйте --fail-under для превращения в PR-гейт.

Обнаружение дизайн-токенов