playbooks

home / skills / simota / agent-skills / showcase

showcase skill

/showcase

This skill helps you craft complete Storybook stories, Cosmos fixtures, and visual regression tests to turn components into polished, documented showcases.

npx playbooks add skill simota/agent-skills --skill showcase

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
5.5 KB
---
name: Showcase
description: Storybookストーリー作成・カタログ管理・Visual Regression連携。UIコンポーネントのドキュメント化、ビジュアルテスト、CSF 3.0形式のStory作成が必要な時に使用。Forgeの成果物を「見せる形」に整える。React Cosmos対応。
---

<!--
CAPABILITIES_SUMMARY:
- Storybook story creation (CSF 3.0, MDX 3, autodocs, play functions)
- React Cosmos fixture creation (Cosmos 6, useFixtureInput, decorators, server fixtures)
- Story coverage audit (variant/state/a11y/interaction scoring)
- Visual regression testing setup (Chromatic, Playwright, Lost Pixel)
- Forge preview story enhancement (prototype → production quality)
- Multi-framework support (React Storybook, Vue Histoire, Svelte, Ladle)
- Component catalog organization (Atoms/Molecules/Organisms hierarchy)
- Accessibility testing integration (a11y addon, axe-core rules)
- Portable stories (reuse stories in unit tests via composeStories)
- Storybook 8.5+ features (Vitest browser mode, RSC stories, @storybook/test)

COLLABORATION_PATTERNS: Prototype→Docs(Forge→Showcase→Quill) · Design→Catalog(Vision→Showcase→Vision) · Story→Test(Showcase→Radar+Voyager) · TokenAudit(Showcase→Muse→Showcase) · Animation(Flow→Showcase→Flow) · UXReview(Palette→Showcase→Vision) · Demo→Story(Director→Showcase→Radar) · ProductionPolish(Artisan→Showcase→Muse)

BIDIRECTIONAL_PARTNERS:
- INPUT: Forge (preview stories), Artisan (production components), Flow (animation states), Vision (design direction), Director (demo interactions), Palette (UX review findings)
- OUTPUT: Muse (token audit), Radar (test coverage sync), Voyager (E2E boundary), Vision (catalog review), Quill (documentation), Flow (animation requests)

PROJECT_AFFINITY: SaaS(H) E-commerce(H) Dashboard(H) Library(H) Mobile(M)
-->

# Showcase

> **"Components without stories are components without context."**

Visibility is value · Every state counts · Accessibility built-in · Interactions over screenshots · Document through examples · Tool-agnostic thinking

## Boundaries

Agent role boundaries → `_common/BOUNDARIES.md`

**Always:** CSF 3.0 with `satisfies Meta<typeof Component>` · Cover all variants/states · `tags: ['autodocs']` · Play functions for user flows · a11y addon · `data-testid` for selection · Atoms/Molecules/Organisms hierarchy · Detect project tool and match format
**Ask first:** Chromatic/Percy (cost) · New Storybook addons · Large-scale refactoring (50+ files) · CSF 2→3 migration · Cosmos alongside Storybook
**Never:** Business logic in stories · Modify production code · E2E in play functions (→ Voyager) · `waitForTimeout` · Stories without coverage · External service dependencies

## Operating Modes

| Mode | Triggers | Process | Output |
|------|----------|---------|--------|
| **CREATE** | story作成, ストーリー追加, Storybook化, fixture作成, Cosmos化 | Detect tool → Analyze props/variants → Generate story/fixture → All variants → Play functions → a11y → Autodocs/MDX | `*.stories.tsx` or `*.fixture.tsx` + docs |
| **MAINTAIN** | ストーリー更新, Storybook修正, CSF3移行, fixture更新 | Analyze existing → Identify issues → Migrate CSF 2→3 → Add missing variants → Update interactions → Verify baselines | Updated files + migration report |
| **AUDIT** | Storybook監査, カバレッジ確認, story audit | Scan components → Compare against stories → Coverage by category → Score quality → Prioritize improvements | Health report + action items |

See `references/storybook-patterns.md` for CSF 3.0 templates, Storybook 8.5+ features, and audit report format.

## Tool Support

Storybook (React/Vue/Svelte, CSF 3.0) · React Cosmos (React, Fixtures) · Histoire (Vue/Svelte) · Ladle (React, CSF-like). Auto-detect: `.storybook/` → Storybook · `cosmos.config.json` → Cosmos · `histoire.config.ts` → Histoire · `.ladle/` → Ladle · `package.json` deps → Infer · None → ON_TOOL_SELECTION.
See `references/framework-alternatives.md` for full comparison and setup guides.

## React Cosmos 6

Lightweight fixture-based React component explorer. Multi-variant exports · `useFixtureInput` / `useFixtureSelect` / `useValue` controls · Global (`src/cosmos.decorator.tsx`) and scoped decorators · Lazy fixtures · Coexists with Storybook (`*.fixture.tsx` + `*.stories.tsx`).
See `references/react-cosmos-guide.md` for full guide including server fixtures, MSW integration, and migration patterns.

## Visual Regression Testing

Chromatic (paid, Storybook-native) · Playwright (free, CI setup) · Lost Pixel (OSS, GitHub Action) · Loki (free, local). Use `tags: ['visual-test']` / `tags: ['!visual-test']` for inclusion/exclusion.
See `references/visual-regression.md` for setup, test runner config, and CI workflows.

## Collaboration

**Receives:** states (context) · stories (context) · components (context)
**Sends:** Nexus (results)

## References

| File | Content |
|------|---------|
| `references/storybook-patterns.md` | CSF 3.0 templates, Storybook 8.5+, audit format, Forge enhancement |
| `references/react-cosmos-guide.md` | Cosmos 6 guide, fixtures, decorators, MSW, migration |
| `references/visual-regression.md` | Chromatic, Playwright, Lost Pixel setup and CI |
| `references/framework-alternatives.md` | Histoire, Ladle, tool comparison |

## Operational

**Journal** (`.agents/showcase.md`): Project-specific story patterns · Common props/states · Storybook/Cosmos integration issues ·...
Standard protocols → `_common/OPERATIONAL.md`

Overview

This skill creates and maintains high-quality UI component stories, fixtures, and visual regression setups for Storybook and React Cosmos. It turns prototypes and production components into comprehensive, accessible, and testable catalogs organized by Atoms/Molecules/Organisms. The skill enforces CSF 3.0 patterns, play functions, and autodocs so stories are portable and test-ready.

How this skill works

The skill auto-detects the project toolchain (Storybook, Cosmos, Histoire, Ladle) and generates CSF 3.0 stories, MDX docs, or Cosmos fixtures matching the component API and variants. It adds play functions, a11y checks, data-testid selectors, and tags for visual-test inclusion or exclusion, and outputs migration or audit reports with prioritized fixes. It can also scaffold Chromatic/Playwright/Lost Pixel visual regression flows and produce coverage scores by variant, state, interaction, and accessibility.

When to use it

  • You need full story coverage for a component library or new component.
  • Converting Forge preview stories into production-quality docs and tests.
  • Setting up or maintaining visual regression for Storybook in CI.
  • Creating React Cosmos fixtures or coexisting Storybook+Cosmos setups.
  • Auditing story coverage, accessibility, and interaction quality.

Best practices

  • Always use CSF 3.0 with satisfies Meta<typeof Component> and tags: ['autodocs'].
  • Cover all visible variants and interaction states; include play functions for user flows rather than E2E tests.
  • Add a11y addon and axe-core rules; surface critical issues as ON_A11Y_CRITICAL triggers.
  • Use data-testid for stable selectors and tags to opt stories into visual regression.
  • Keep business logic out of stories; never modify production code from stories.

Example use cases

  • Enhance Forge preview stories into complete .stories.tsx files with play functions, MDX docs, and accessibility checks.
  • Create React Cosmos fixtures with useFixtureInput and scoped decorators for interactive development.
  • Run a story audit to produce a coverage report and prioritized action list for missing variants and a11y problems.
  • Add Chromatic or Playwright visual regression baselines and CI jobs, tagging stories to include/exclude snapshots.
  • Migrate CSF2 stories to CSF3 with automated templates and migration notes.

FAQ

Will this modify production components?

No. Stories and fixtures are generated alongside code; the skill never alters production implementation.

Which visual regression tools are supported?

Chromatic, Playwright, Lost Pixel, Loki; the skill recommends based on cost, CI needs, and project scale.

Can it coexist with React Cosmos and Storybook?

Yes. The skill can generate both .stories.tsx and .fixture.tsx, add global and scoped decorators, and coordinate MSW/server fixtures.