storybook · diff

git:20260702.87865ea to git:20260722.147335c

3 added, 68 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: storybook
description: Use when writing or reviewing Storybook stories (`.stories.tsx`) for React components.
---
# Storybook Component Stories
- ## Which Components Can Have Stories?
-
- Only create stories for components that **do not** do any of the following:
-
- - Depend on context.
- - Fetch data via any private API, including Langfuse’s own tRPC API.
-
- Stories should follow the `ComponentName.stories.tsx` filename pattern. Components covered by stories should have exactly one exported or public component.
-
- If this is not the case, suggest splitting up the file that includes the component to be covered first.
-
- Be mindful of the breadth a story covers. A story should show a component in isolation. Page-level compositions should be rare and intentional.
-
- ## What to Do If a Component Violates the Criteria
-
- Suggest abstracting a presentational component that does not violate the criteria and receives relevant data via props.
-
- Make sure the props are well-defined using TypeScript.
-
- Keep the existing component, but update it to use the newly created component for rendering. These presentational components are easier to test and easier to reuse.
-
- ## How Stories Should Be Written
-
- - Use "CSF Next" format by default.
- - Cover only the relevant component by default.
- - Do not use `args` on the meta story if most stories override these. Instead, define the args on each story.
- - Avoid custom render functions by default.
- - Do not define helper components inside story files unless the helper component is reused by multiple stories. For one-off setup, inline the stateful render logic directly in the story `render` function.
- - Never use `decorators` to add styling or layout to a story. Stories should render the components as they are.
- - Use `satisfies` and typed Storybook metadata so invalid args, decorators, and play functions are type-checked.
- - Use play functions to test user-relevant interactions after render, not to compensate for complex setup or hidden dependencies.
- - Prefix stories whose primary purpose is interaction test coverage with `(Test)` in the Storybook display name, for example `name: "(Test) Opens Menu"`.
- - Keep `(Test)` stories sorted at the bottom of the file so showcase and product-facing stories stay grouped first.
- - Name stories after the state they represent, not the implementation. Also do not include the component name in the story name.
- - Prefer: `Default`, `Empty`, `WithLongName`, `Error`, `Disabled`, `Loading`
- - Avoid: `Test1`, `CustomRenderExample`, `ButtonWithLongNameAndIcon`
- - Set callbacks up as Storybook Actions by default:
-
- ```ts
- import { fn } from "storybook/test";
- ```
-
- - Avoid large fixtures.
- - Use the smallest meaningful data shape needed to render the state.
- - If fixtures are required and may be shared, check whether a reusable helper function exists. Otherwise, create one for defining the fixture.
-
- ## Variant and Design Showcase Stories
-
- If a component has many variants, and the point of the story is to showcase the design of a component rather than its functionality, stories may render the component multiple times.
-
- For example, a `Button` with a `size: "sm" | "md" | "lg"` prop may have a story that shows three buttons side by side.
-
- If the button also has a `variant: "primary" | "secondary"` prop, consider using a matrix-like UI that showcases all possible combinations.
-
- These compositional stories **should not** contain Storybook play functions. They should also not allow the Storybook user to customize the predefined args, such as `size` and `variant`, via Storybook args. Having an arg for non-bound props, such as `text`, may be acceptable.
-
- ## Authoring MDX Docs
-
- - Use `.mdx` for prose docs and guides that sit alongside stories.
- - Keep `.mdx` files simple by default: standard markdown plus Storybook docs blocks such as `Meta` and `Canvas` are usually enough.
- - Do not build bespoke page layouts in `.mdx` with exported inline-styled React components unless there is a strong reason.
- - If docs need reusable typography, spacing, or docs-page chrome, add that once in Storybook preview/docs container setup rather than re-implementing it in a single `.mdx` file.
- - Keep illustrative examples in `.stories.tsx`; keep narrative and explanation in `.mdx`.
- - If an example needs a small wrapper in a story, keep it minimal and focused on presenting the example rather than recreating page design inside Storybook.
-
- ## Additional Information
-
- - We do not use MSW and are not planning to add it.
+ Before writing or reviewing Storybook stories, read and follow the canonical
+ [Writing Good Stories](../../../web/storybook/docs/WritingGoodStories.mdx)
+ guide.