adilallo
115 lines
4.0 KiB
Plaintext
115 lines
4.0 KiB
Plaintext
---
|
|
description: Storybook story conventions — location, naming, titles, decorators
|
|
globs: stories/**/*.{js,jsx,ts,tsx,mdx},.storybook/**/*.{js,ts}
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Where stories live
|
|
|
|
All stories live in the top-level `stories/` folder. Two layout rules:
|
|
|
|
- **Design-system components** mirror `app/components/`. A component at
|
|
`app/components/<bucket>/<Name>` gets `stories/<bucket>/<Name>.stories.js`.
|
|
- **Create-flow material** has two carve-outs:
|
|
- `stories/create-flow/` — shared create-flow pieces that aren't in
|
|
`app/components/` (e.g. composed wizard fragments).
|
|
- `stories/pages/` — integration stories that exercise an entire
|
|
`app/(app)/create/screens/<...>` screen as it appears in the wizard.
|
|
|
|
| Source | Story location |
|
|
| --------------------------------- | --------------------------------------- |
|
|
| `app/components/controls/Chip` | `stories/controls/Chip.stories.js` |
|
|
| `app/components/buttons/Button` | `stories/buttons/Button.stories.js` |
|
|
| `app/(app)/create/screens/.../FooScreen`| `stories/pages/FooPage.stories.js` |
|
|
| Shared create-flow fragment | `stories/create-flow/<Name>.stories.js` |
|
|
|
|
Do **not** colocate `*.stories.*` next to components. The Storybook config
|
|
(`.storybook/main.js`) only globs `stories/**`.
|
|
|
|
# File naming
|
|
|
|
- `<ComponentName>.stories.js` — matches 69/70 existing files.
|
|
- Use `.tsx` only when the story genuinely needs types (rare; prefer JS to
|
|
match the codebase convention).
|
|
- Variants get a suffix: `Button.visual.stories.js`,
|
|
`Footer.responsive.stories.js`.
|
|
|
|
# Default export shape (CSF2)
|
|
|
|
```javascript
|
|
import MyComponent from "../../app/components/<area>/MyComponent";
|
|
|
|
export default {
|
|
title: "Components/<SubFolder>/MyComponent",
|
|
component: MyComponent,
|
|
parameters: {
|
|
layout: "centered",
|
|
docs: {
|
|
description: {
|
|
component: "Short description of what the component is for.",
|
|
},
|
|
},
|
|
},
|
|
argTypes: {
|
|
variant: {
|
|
control: { type: "select" },
|
|
options: ["filled", "outline"],
|
|
description: "The variant (Figma prop)",
|
|
},
|
|
onClick: { action: "clicked" },
|
|
},
|
|
};
|
|
|
|
export const Default = { args: { variant: "filled" } };
|
|
```
|
|
|
|
## Title hierarchy
|
|
|
|
- Design-system components → `Components/<SubFolder>/<Name>` (e.g.
|
|
`Components/Controls/Checkbox`).
|
|
- Pages → `Pages/<PageName>` (folder: `stories/pages/`).
|
|
- Create flow shared pieces → `Create Flow/<Name>`.
|
|
|
|
## `argTypes`
|
|
|
|
For every Figma enum prop (`variant`, `size`, `state`, `mode`, `palette`,
|
|
…) expose a `select` control listing the **lowercase** option set, sourced
|
|
from the matching `*_OPTIONS` const in `lib/propNormalization.ts`. See
|
|
`.cursor/rules/component-props.mdc`.
|
|
|
|
# Rely on the global preview — don't re-wrap
|
|
|
|
`.storybook/preview.js` already provides:
|
|
|
|
- `MessagesProvider` with `messages/en` → access copy via `useMessages()`
|
|
inside stories exactly like app code. Never hard-code user-facing strings.
|
|
- `app/globals.css` + `.font-inter` wrapper → design tokens and fonts are
|
|
already present.
|
|
|
|
Do **not** add your own `MessagesProvider`, font wrapper, or token setup in a
|
|
story. If you need a new global, update `preview.js`.
|
|
|
|
# Interaction tests (`play`)
|
|
|
|
Use `storybook/test` for interaction assertions — not `@testing-library/*`
|
|
directly. This matches `Checkbox.stories.js` and stays compatible with the
|
|
Vitest portable-stories runner in `.storybook/vitest.setup.js`.
|
|
|
|
```javascript
|
|
import { within, userEvent, expect } from "storybook/test";
|
|
|
|
export const Interactive = {
|
|
play: async ({ canvasElement }) => {
|
|
const canvas = within(canvasElement);
|
|
await userEvent.click(canvas.getByRole("checkbox"));
|
|
expect(canvas.getByRole("checkbox")).toHaveAttribute("aria-checked", "true");
|
|
},
|
|
};
|
|
```
|
|
|
|
# Coverage expectation
|
|
|
|
Every new component in `app/components/**` ships with a story. Screens in
|
|
`app/(app)/create/screens/**` ship with a `stories/pages/<Name>Page.stories.js`
|
|
entry. A new component without a story is considered incomplete.
|