# Cursor Designer Storybook > Builds and maintains Storybook as the central design-system component vitrine for Vue/Nuxt or React/Next projects. Discovers the project's components, tokens, and naming first, then applies a fixed Storybook Docs anatomy (Preview ground muted|card|float, token-first Usage, docs chrome, MDX mirrors, framework stubs). Use for Storybook setup, DS catalog, migration from /design-system, Foundations, Preview canvas rules, or /storybook — not Soft*-specific. - Skill: `igrlebed/cursor-designer-storybook` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add igrlebed/cursor-designer-storybook` - Raw SKILL.md: https://api.skillmd.com/api/skills/igrlebed/cursor-designer-storybook/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: igrlebed (https://skillmd.com/u/igrlebed) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/igrlebed/cursor-designer-storybook --- # Cursor Designer · Storybook Storybook = **единственная витрина** design system проекта, не параллельный слой «docs рядом с приложением». **Структура и оформление Storybook** (IA, Docs-секции, Preview ground, stubs, зеркала) — канон этого скилла. **Имена компонентов, токены, пути, copy** — **только из текущего проекта**. Канон проекта (если есть): `docs/STORYBOOK.md`. Эталон структуры Docs внутри SB: **Шаблоны → Component docs**. Детали: [reference.md](reference.md). --- ## Шаг 0 — разведка проекта (обязательно) Перед любым scaffold / новым story / миграцией зафиксируй в ответе одной короткой карточкой: | Поле | Где искать | | --- | --- | | Framework | Nuxt/Vue или Next/React — из ARCHITECTURE / package.json | | UI kit | Nuxt UI / shadcn / PrimeReact | | Корень SB-пакета | `package.json` со `storybook` / `build-storybook` (монорепо: часто `web/`, `apps/web`, корень) | | SoT компонентов | `components/ds/`, `components/ui/`, `layers/*/components`, design-system package | | Префикс / naming | `Soft*`, `Ui*`, `App*`, kit wrappers — как в репо | | Токены | CSS vars (`--space-*`, `--color-*`), theme, Tailwind theme, kit tokens | | Docs-chrome SB | уже есть (`Sb*`, `Docs*`) или создать нейтральный (`SbDocsPage` …) | | Параллельная витрина | `/design-system`, `/ui`, demo pages — подлежит thin redirect | | Язык UI / глоссарий | `docs/UX_SPECIFICATION.md`, mocks, PRODUCT.md | Дальше все примеры и импорты — **в naming проекта**, не Soft*. --- ## Когда применять | Запрос | Действие | | --- | --- | | Storybook / витрина DS / Docs компонентов | этот скилл + Шаг 0 | | Перенос с `/design-system` (или аналога) | live component в Docs + stubs, не HTML-анатомия | | Preview серый/белый | ground muted \| card \| float по типу specimen | | Новый компонент в SB | шаблон Component docs + DoD | | Зеркало `docs/*.md` в SB | MDX + `?raw` relative import | Не подменяет: `cursor-designer-visual` (продуктовая вёрстка), `ux-specification-builder` (UX-спека). Рядом: `cursor-designer-core`, `cursor-designer-handover` (`build-storybook` = блокер передачи витрины). --- ## Принципы (не ломать) 1. **Назначение, не API** — lead = что пользователь *делает* компонентом. 2. **Иерархия** — один primary на зону. 3. **Правила рядом с демо** — Usage + Tip → sibling-компонент того же DS. 4. **A11y конкретно** — какие props / когда. 5. **Variants = stories** — ось + *зачем*. 6. **Do/Don’t** ≥2 пары. 7. **Related = роли**, не список имён. 8. **Token-first** — в Usage только токены проекта; сырой px/hex при наличии токена запрещён. 9. Чужой bootstrap Storybook — только старт; дальше канон этого скилла + DS проекта. --- ## Правило витрины 1. Preview = **живой** компонент из SoT проекта, не HTML-анатомия. 2. Stores / router / overlays / map / framework APIs → stubs в `.storybook/`, не «см. demo page». - Vue: Pinia, vue-router, Nuxt shims - React: context providers, Next navigation mocks as needed 3. Gap в Docs = **баг витрины** (чинить SB). 4. Старая витрина в приложении — thin redirect / баннер «см. Storybook». 5. Preview ground — [reference.md](reference.md#preview-ground); маппинг specimen → ground вывести из **визуала компонентов проекта**. --- ## IA сайдбара (порядок) ``` Введение Документы ← зеркала SoT (правила SB, UX-спека, …) через ?raw Шаблоны ← Component docs (эталон структуры, без live component) Foundations ← Spacing → Colors → Type → Radius → Shadow → Motion (оставь только токены, которые есть в проекте) Components/* ← компоненты DS по группам каталога проекта ``` `storySort.order` в `.storybook/preview.ts` (или аналог) = синхрон с IA. Язык сайдбара: язык документации проекта (часто русский). --- ## Файлы компонента в SB ### Vue ``` stories/components//.stories.ts stories/components//Docs.vue # docs-chrome + секции ``` ### React ``` stories/components//.stories.tsx stories/components//Docs.tsx # docs-chrome + секции ``` `` и `` — из структуры SoT проекта. **Docs-chrome** (только SB, не продукт): если в проекте нет — создать нейтральный набор: `SbDocsPage`, `SbDocsHeader`, `SbDocsSection`, `SbPreviewBlock`, `SbCallout`, `SbDoDont`, `SbRelated`, `SbTokenList`, `SbTokenTable`. Если уже есть свой chrome — **расширяй его**, не плоди второй. В оркестраторах / overlays — **явные** импорты DS-компонентов (auto-import в SB часто ломается → утечка слотов в Preview). --- ## Docs: порядок секций Header → When/When not → Preview → Import → Props → Usage → Accessibility → Variants → Do’s and Don’ts → Use cases (по сложности) → Related. Новый компонент: копировать **Шаблоны → Component docs**, заполнить контентом проекта, DoD из [reference.md](reference.md#dod). Визуал Docs (типографика, отступы chrome, цвета canvas) — из **токенов проекта** (или DESIGN.md / theme), не из чужого Soft*-скина. --- ## Зеркала markdown в Storybook SoT остаётся в `docs/*.md`. В SB — MDX-зеркало: ```ts // stories/guides/docs-sources.ts export { default as storybookRulesMd } from "../../../docs/STORYBOOK.md?raw"; export { default as uxSpecificationMd } from "../../../docs/UX_SPECIFICATION.md?raw"; ``` ```mdx import { Meta, Markdown } from "@storybook/addon-docs/blocks"; import { storybookRulesMd } from "./docs-sources"; {storybookRulesMd} ``` - Relative path + `?raw` (alias `@docs` в MDX dev часто ломается). - Vite: `server.fs.allow` на repo `docs/`. - Dev: правки `.md` подхватываются; static build — нужен rebuild. - Introduction MDX: **HTML ``**, не GFM-таблицы. - Имена с `*` в MDX экранировать или держать в HTML. Manager theme: **hex** в `manager.ts`, не `oklch()` (ломает сайдбар). Цвета manager — из brand/tokens проекта, конвертированных в hex. --- ## Workflow: bootstrap Storybook на новом проекте ``` 1. Шаг 0 — карточка проекта 2. Поднять Storybook (Vite + Vue/Nuxt или React) в корне пакета приложения 3. Docs-chrome + Шаблоны/Component docs 4. Foundations из реальных токенов 5. 1–2 пилотных компонента с полным Docs + DoD 6. docs/STORYBOOK.md + зеркало в «Документы» 7. Thin redirect со старой витрины (если была) 8. npm run build-storybook — зелёный ``` ## Workflow: новый компонент в Storybook ``` 1. Стабилизировать компонент в SoT 2. stories + Docs с Шаблоны/Component docs 3. Preview ground по типу specimen (из визуала проекта) 4. DoD 5. Статус во Введение 6. CHANGELOG при крупном шаге витрины ``` ## Workflow: починка Preview / stubs ``` 1. Воспроизвести в Docs 2. Явные импорты DS в дочерних overlays 3. Store / router / ClientOnly / framework shims в .storybook 4. Не отсылать на demo-страницу приложения ``` --- ## Анти-паттерны - Hardcode чужого префикса (Soft*, Ui*) в проект, где его нет - Controls-песочница без Usage / DoDon’t - Сырой px / hex в Usage при токене проекта - Светлый secondary-control на `ground="card"` - Chart / markdown-document на `muted` - `float` + `ground="card"` - Anatomy HTML вместо live component - Параллельная живая витрина вне Storybook - Править зеркало MDX вместо SoT `docs/*.md` --- ## Команды Из корня пакета со Storybook: ```bash npm run storybook # обычно :6006 npm run build-storybook # CI / проверка ``` Красный `build-storybook` = блокер handover витрины. Ручной вызов: `/storybook` → этот скилл.