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.

Шаг 0 — разведка проекта (обязательно)

Перед любым scaffold / новым story / миграцией зафиксируй в ответе одной короткой карточкой:

Дальше все примеры и импорты — в naming проекта, не Soft*.

Когда применять

Не подменяет: 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; маппинг 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/<group>/<ComponentName>.stories.ts
stories/components/<group>/<ComponentName>Docs.vue   # docs-chrome + секции

React

stories/components/<group>/<ComponentName>.stories.tsx
stories/components/<group>/<ComponentName>Docs.tsx   # docs-chrome + секции

<group> и <ComponentName> — из структуры 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.

Визуал Docs (типографика, отступы chrome, цвета canvas) — из токенов проекта (или DESIGN.md / theme), не из чужого Soft*-скина.

Зеркала markdown в Storybook

SoT остаётся в docs/*.md. В SB — MDX-зеркало:

// stories/guides/docs-sources.ts
export { default as storybookRulesMd } from "../../../docs/STORYBOOK.md?raw";
export { default as uxSpecificationMd } from "../../../docs/UX_SPECIFICATION.md?raw";

import { Meta, Markdown } from "@storybook/addon-docs/blocks";
import { storybookRulesMd } from "./docs-sources";
<Meta title="Документы/Правила Storybook" />
<Markdown>{storybookRulesMd}</Markdown>

• Relative path + ?raw (alias @docs в MDX dev часто ломается).
• Vite: server.fs.allow на repo docs/.
• Dev: правки .md подхватываются; static build — нужен rebuild.
• Introduction MDX: HTML <table>, не 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:

npm run storybook          # обычно :6006
npm run build-storybook    # CI / проверка

Красный build-storybook = блокер handover витрины.

Ручной вызов: /storybook → этот скилл.