Writing UI stories
Components in @flow-state-dev/ui ship with Storybook stories. A story is a file that exports one or more example uses of a component, and Storybook is a small dev server that renders each one in isolation. The hosted build lives at storybook.flow-state.dev and gets a preview URL on every PR that touches packages/ui.
If you're new to the registry itself, start with the UI overview.
Where stories live
Stories sit next to the component they cover:
packages/ui/registry/components/message.tsx
packages/ui/registry/components/message.stories.tsx
The Storybook glob picks them up by filename (*.stories.tsx). The registry build only copies files that are explicitly listed in registry.json, so stories never leak into the published registry.
Running Storybook locally
pnpm --filter @flow-state-dev/ui storybook
That starts the dev server on http://localhost:6006. To run the same build CI runs:
pnpm --filter @flow-state-dev/ui storybook:build
The CI job runs storybook:build on every PR, so a broken story fails the check before it reaches the deploy step.
Anatomy of a story
Stories use Storybook's Component Story Format 3. Each file has a default export with metadata and named exports for each variant.
import type { Meta, StoryObj } from "@storybook/react-vite";
import { Message } from "./message";
import { messageItem } from "../../stories/fixtures/items";
const meta = {
title: "Components/Message",
component: Message,
} satisfies Meta<typeof Message>;
export default meta;
type Story = StoryObj<typeof meta>;
export const User: Story = {
args: { item: messageItem({ role: "user", text: "Hi" }) },
};
export const Assistant: Story = {
args: { item: messageItem({ role: "assistant", text: "Hello." }) },
};
The title decides the sidebar position in Storybook. Use Components/<Name> so everything lands under one folder.
Using fixtures
Most components accept Flow State item types directly. packages/ui/stories/fixtures/ has typed factories for the common shapes:
messageItem,reasoningItem,toolItem,componentItem,sourceItem— single items.plainConversation,toolUseConversation— multi-item sessions.makeTask,makeTaskChange,makeBoardMeta— task-board state for<TaskPlan />.
Compose those instead of hand-rolling item shapes in each story. If your component needs a shape the fixtures don't cover, add a factory there rather than inlining one.
When you need FlowProvider
Components that read useFlowContext().renderers (currently RequestGroup and ChatAssistant) need a FlowProvider in the tree. The global preview.tsx already wraps every story in <FlowProvider renderers={chatAssistantRenderers}>, so most of the time you don't need to think about it. Override it per-story by wrapping with your own FlowProvider if you want a different renderer registry.
<TaskPlan /> reads from <SessionItemsProvider /> rather than FlowProvider. Wrap it manually in the story when you want to drive it from a fixture session — see task-plan.stories.tsx for the pattern.
Stories for @flow-state-dev/react components
The react package's visual components (FlowNavigator, Roster, BoardColumns and WorkerDetail) have their stories in the same Storybook, under packages/ui/stories/react/, in the React folder of the sidebar. The package has no Storybook of its own.
These components fetch their own data, through the client prop. A story picks the state by passing a fake client from packages/ui/stories/fixtures/workforce.ts. A fake only needs the methods the component calls: resources.listCollectionItems for the list panels, resources.getCollectionItemState for WorkerDetail, and flows plus sessions.list for FlowNavigator.
import { Roster } from "@flow-state-dev/react";
import { failingRowsSource, loadingRowsSource, rowsSource } from "../fixtures/workforce";
export const Loading: Story = { args: { client: loadingRowsSource } };
export const Empty: Story = { args: { client: rowsSource([]) } };
export const Failed: Story = { args: { client: failingRowsSource("Failed to load the roster") } };
A fake that never answers shows the loading state, one that returns no rows shows the empty state, and one that throws shows the component's error message with its Retry button. There are matching factories for single-item reads (itemSource), the flow list (flowsSource) and session lists (sessionsSource).
Create each fake client once, at module scope, as above. A client created inside a story's render function is a new object on every render, and the component restarts its fetch each time it sees a new client.
These components ship no CSS. A host styles them through the --fsd-nav-* and --fsd-panel-* custom properties, and .storybook/preview.css sets those from the theme tokens, so these stories follow the Theme toolbar like the rest.
Common variants worth writing
There's no fixed rule, but these are the ones reviewers look for:
- Default — the most common rendering path.
- Streaming / in-progress — for components that show a status state.
- Error — if the component renders an error case.
- Empty — for containers that have a zero-state.
Two or three named exports per component is typical.
Verifying before commit
pnpm --filter @flow-state-dev/ui storybook:build is the same check CI runs. If it passes locally, the smoke job will pass on the PR. Visual review happens on the per-PR preview URL Vercel posts as a check.
Further reading
- UI overview — what the registry is and how it's distributed.
- Storybook CSF 3 reference — full story format spec.