菜单
Storybook conventions for packages/ui-react — where stories live, CSF3 story shape, the a11y and docs addons, token/theme stories, and how stories relate to the four co-located Vitest projects. Use when adding or changing a *.stories.tsx file, or when documenting a ui-react component.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Lordpluha/bitrate-music --skill storybook命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | storybook |
| description | Storybook conventions for packages/ui-react — where stories live, CSF3 story shape, the a11y and docs addons, token/theme stories, and how stories relate to the four co-located Vitest projects. Use when adding or changing a *.stories.tsx file, or when documenting a ui-react component. |
| license | MIT |
| metadata | {"author":"lordpluha","version":"1.0.0"} |
Storybook 10 with @storybook/react-vite, plus @storybook/addon-a11y and
@storybook/addon-docs. It belongs to packages/ui-react only — the apps do not run it.
pnpm --filter @spotify/ui-react storybook # dev
pnpm --filter @spotify/ui-react build-storybook # static build
Co-located with the component, alongside its four spec files. A new ui-react component's
full set is:
packages/ui-react/src/components/ui/<name>/
<name>.tsx
<name>.stories.tsx
<name>.unit-spec.tsx
<name>.int-spec.tsx
<name>.snapshot-spec.tsx
<name>.screenshot-spec.tsx
index.ts
.stories.tsx is required for a new component — it is checked by FSD-5 in
.claude/rules/architecture-checklist.md. Token/foundation stories live beside what they
document (src/styles/radius.stories.tsx, spacing.stories.tsx, shadow.stories.tsx).
src/styles/palette.stories.tsx and themes.stories.tsx get their data from
src/styles/token-docs.ts, which parses the stylesheets themselves through
import.meta.glob('./themes/**/*.css', { query: '?raw' }). They therefore always show
exactly what the CSS declares: a role added to a part-file appears without anyone editing a
story, and a renamed one cannot leave a stale entry behind.
Never add a colour token to one of those files by hand — a hand-maintained list rots the
moment a token is renamed. Declare it in the @theme and :root.light blocks of the
part-file that should own it, and the story follows.
.storybook/preview.tsx puts a Theme control in the toolbar; it toggles the light
class on <html>, the same switch the apps use. Check any new component in both themes
before calling it done — dark is the default, so a light-theme regression is easy to miss.
import type { Meta, StoryObj } from '@storybook/react-vite'
import { Badge } from './badge'
const meta = {
title: 'UI/Badge',
component: Badge,
parameters: { layout: 'centered' },
tags: ['autodocs'],
argTypes: { variant: { control: 'select', options: ['default', 'secondary'] } },
} satisfies Meta<typeof Badge>
export default meta
type Story = StoryObj<typeof meta>
export const Default: Story = { args: { children: 'New' } }
export const Secondary: Story = { args: { variant: 'secondary', children: 'Beta' } }
satisfies Meta<typeof Component> is what makes args type-checked against the real props —
without it, a renamed prop leaves a silently broken story. tags: ['autodocs'] generates the
docs page from the component's types and TSDoc.
One story per meaningful state, not per prop permutation:
disabled, loading, error, empty,
long-content overflow, and truncation.The long-content story earns its place more often than any other — most layout bugs in a shared component are a label nobody tried at 60 characters.
addon-a11y runs axe on the rendered story and reports violations in the panel. Treat a
violation as a component defect: a missing accessible name on an icon-only control, contrast
below AA, a non-semantic interactive element. apps/docs/docs/brand/a11y.md is the contract.
They do different jobs; a story is not a test:
| Artifact | Answers |
|---|---|
.stories.tsx | What does it look like, in every state a human should review? |
.unit-spec.tsx | Does it behave correctly in isolation? |
.int-spec.tsx | Does it behave correctly under real user interaction? |
.snapshot-spec.tsx | Did the DOM change unintentionally? |
.screenshot-spec.tsx | Did the rendered pixels change unintentionally? |
.screenshot-spec.tsx is the one that overlaps — it is the automated guard, the story is the
human-review surface. Keep both.
.storybook/preview is not importing @spotify/ui-react/styles/*.css.packages/ui-react must not import from apps/*; a story that needs
app context is testing the wrong thing at the wrong layer.Do not guess an API from memory. In order:
node_modules/storybook is what this repo actually runs; the
docs site describes the latest release, which may not be it.
node -p "require('storybook/package.json').version"
ui-react-rules skill — where components live, search-before-adding, Base UI.vitest skill — the four co-located spec projects.playwright skill — the Chromium provider behind screenshot specs..claude/rules/architecture-checklist.md — FSD-5, the required component file set.