twenty-ui/testing exposes Storybook decorators and preview layout helpers. Configure styles and a ThemeProvider in your Storybook preview before rendering themed components.
Story roles
Start each component guide with aDisplay story showing one representative, usable example. Follow it with Usage code that reproduces the preview using public imports. Compound components demonstrate their parts together. Providers and accessibility helpers demonstrate their effect in context.
Add a Catalog when a labeled comparison helps readers choose between visual options. Group variants, sizes, colors, and states separately; use a matrix only when comparing two dimensions together is useful. A simple component can use one alternative example. Dialogs, menus, and other interactive components usually need focused examples for each workflow.
Preserve comprehensive screenshot coverage in separate VisualRegression stories, including dark themes and variant matrices. Tag those stories with !autodocs and keep them out of the component guides.
Name other stories after what they demonstrate, such as Controlled, WithValidation, or MultipleSelection. Keep interaction checks in separate stories with play functions. The display and other documentation previews remain usable by the reader without automated actions.
ComponentDecorator
ComponentDecorator wraps a story in ComponentStorybookLayout. Set parameters.container.width and parameters.container.height in pixels. It also reads the story’s inverted and accent args to choose an optional background.
GroupedCatalog
GroupedCatalog gives curated catalogs a shared layout for headings, wrapping rows, and spacing. Each group has a label and an examples array. Every example needs a unique label within its group; it can carry any other data used by renderExample.
{ label: string; examples: CatalogExample[]; }[]
required
Labeled groups of examples. Each example has a unique label within its group and can include additional data for the renderer.
(example: CatalogExample) => ReactNode
required
Renders one example, including its visible label or accessible name. The layout supplies the surrounding cell and spacing.
CatalogDecorator
CatalogDecorator renders combinations of up to four dimensions from parameters.catalog.dimensions. Each dimension has a name, values, a props(value) mapper, and an optional labels(value) formatter. The mapper returns the props for that cell. parameters.catalog.options.elementContainer accepts width, style, and className.
ComponentStorybookLayout
Use the layout directly when composing a preview outside a decorator. It accepts one child element.string
Background color override.
Element
required
The component preview element.
number
Container height in pixels. Defaults to fit-content.
number
Container width in pixels. When omitted, the container has a 300px minimum width.
Documentation previews
Stories embedded in the documentation must be presentational and have noplay function. Keep interaction tests in separate stories. Share explicit args, render, decorators, and parameters when needed, rather than spreading an interaction story into a preview. The documentation embed check rejects stories marked with Storybook’s play-fn tag, including inherited play functions.
Each component guide’s first embed must reference a story exported as Display. Give every embed a descriptive title for its iframe and enough height to show the example. The shared preview supplies light and dark tabs and a link to Storybook, where readers can use controls to explore props.
Run npx nx check:ui-stories twenty-docs to check the required display, preview titles, references, and presentation rules. Run npx nx check:ui twenty-docs to validate the generated API references and typecheck copyable examples.