Template: Story Specification

This template is used during Phase A of the Use Case to UX workflow. Copy it to your project directory and fill in the <!-- REPLACE: ... --> placeholders.

When filled in, the document title should follow the pattern: <Entity Domain Name> UX — Story Specifications.

Companion documents: Scope Analysis, Application Conventions (produced alongside this document in Phase A).

---

Project: Date: Status: Companion: Scope Analysis (in the same project directory)

---

1. Overview

1.1 Conventions

Story types:

• Multi-step workflows (create, edit, view-then-edit) use the createUseCaseStories framework, producing three variants for each story:
  • Interactive — for manual exploration; no play function
  • Stepwise — auto-advances step by step with visible annotations; no play function
  • Automated — runs the full interaction headlessly via a play function
• Single-interaction stories use standard Storybook stories (export const Default: Story = {}) with a play function to automate assertions. No createUseCaseStories wrapper is needed.

Testing depth:

Documentation links: Each story group includes a Description MDX page that links to the canonical specification on the documentation site using the docsUrl() helper.

1.2 File Organization

src/use-cases/reference/<!-- REPLACE: domain-slug -->/
├── _shared/                              # Hidden from Storybook sidebar
│   ├── types.ts                          # <!-- REPLACE: e.g., "Entity type definitions" -->
│   ├── mock-data.ts                      # <!-- REPLACE: e.g., "Mock records (N entities)" -->
│   ├── msw-handlers.ts                   # <!-- REPLACE: e.g., "All MSW handlers (query, CRUD)" -->
│   ├── <!-- REPLACE: shared-component.tsx --> # <!-- REPLACE: e.g., "Shared Page component" -->
│   └── <!-- REPLACE: other-shared.tsx -->     # <!-- REPLACE: e.g., "Additional shared component" -->
│
├── <!-- REPLACE: use-case-group-1/ -->   # <!-- REPLACE: Use Case ID, e.g. REF::WR::0001 -->
│   ├── <!-- REPLACE: description.mdx --> # Description MDX page
│   ├── <!-- REPLACE: story-1.stories.tsx -->  # <!-- REPLACE: Scenario IDs covered -->
│   └── <!-- REPLACE: story-2.stories.tsx -->  # <!-- REPLACE: Scenario IDs covered -->
│
├── <!-- REPLACE: use-case-group-2/ -->   # <!-- REPLACE: Use Case ID -->
│   ├── <!-- REPLACE: description.mdx -->
│   └── <!-- REPLACE: story-1.stories.tsx -->
│
└── <!-- REPLACE: use-case-group-N/ -->   # <!-- REPLACE: Use Case ID -->
    ├── <!-- REPLACE: description.mdx -->
    └── <!-- REPLACE: story-1.stories.tsx -->

1.3 Storybook Sidebar Structure

Use Cases / Reference / <!-- REPLACE: Domain Display Name --> /
├── <!-- REPLACE: Use Case Group 1 --> /
│   ├── Description                       (MDX)
│   ├── <!-- REPLACE: Story Title 1 -->   (stories)
│   └── <!-- REPLACE: Story Title 2 -->   (stories)
├── <!-- REPLACE: Use Case Group 2 --> /
│   ├── Description                       (MDX)
│   └── <!-- REPLACE: Story Title 1 -->   (Interactive, Stepwise, Automated)
└── <!-- REPLACE: Use Case Group N --> /
    ├── Description                       (MDX)
    └── <!-- REPLACE: Story Title 1 -->   (stories)

---

2. Shared Infrastructure (_shared/)

2.1 Types (_shared/types.ts)

File	Description	Built By
_shared/types.ts

2.2 Mock Data (_shared/mock-data.ts)

File	Description	Built By
_shared/mock-data.ts

Data variety requirements:

2.3 MSW Handlers (_shared/msw-handlers.ts)

File	Description	Built By
_shared/msw-handlers.ts

<!-- REPLACE: METHOD /api/arda/entity/query -->

Parameter	Type	Required	Default	Description

<!-- REPLACE: METHOD /api/arda/entity/:entityId -->

2.4 (_shared/<!-- REPLACE: component-file.tsx -->)

Key props:

Prop	Type	Required	Description

File	Description	Built By
_shared/<!-- REPLACE: component-file.tsx -->

---

3. Story Specifications

---

3.1 (<!-- REPLACE: REF::DOMAIN::0001 -->)

3.1.0 Description MDX (<!-- REPLACE: use-case-group/description.mdx -->)

Title: "Use Cases/Reference/<!-- REPLACE: Domain Display Name -->/<!-- REPLACE: Use Case Group Name -->/Description"

Content:

• Link to documentation: docsUrl('<!-- REPLACE: /product/use-cases/reference-data/domain/page/#anchor -->')

---

3.1.1 (<!-- REPLACE: DOMAIN::0001::0001 -->)

Story ID: <!-- REPLACE: DOMAIN::0001::0001 --> File: <!-- REPLACE: use-case-group/story-title.stories.tsx --> Storybook title: Use Cases/Reference/<!-- REPLACE: Domain Display Name -->/<!-- REPLACE: Use Case Group Name -->/<!-- REPLACE: Story Title --> Type:

Variants:

Meta code template:

import { expect, userEvent, within, screen, waitFor } from '@storybook/test';
import type { Meta, StoryObj } from '@storybook/react-vite';
// REPLACE: import the component under test and any shared infrastructure
import { /* REPLACE: ComponentName */ } from '../_shared/<!-- REPLACE: component-file -->';
import { /* REPLACE: mockData */ } from '../_shared/mock-data';
import { /* REPLACE: handlers */ } from '../_shared/msw-handlers';

const meta: Meta<typeof /* REPLACE: ComponentName */> = {
  title: 'Use Cases/Reference/<!-- REPLACE: Domain Display Name -->/<!-- REPLACE: Use Case Group Name -->/<!-- REPLACE: Story Title -->',
  component: /* REPLACE: ComponentName */,
  parameters: {
    msw: { handlers: [/* REPLACE: handler references */] },
    // REPLACE: add layout, chromatic, or other parameters as needed
  },
  decorators: [fullAppProviders],
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    // REPLACE: initial args
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    // REPLACE: play function assertions
  },
};

---

3.1.2 (<!-- REPLACE: DOMAIN::0001::0002 -->)

---

3.2 (<!-- REPLACE: REF::DOMAIN::0002 -->)

---

4. Summary Table

Story ID	Story Title	Files to Create	Files to Modify
_shared	Shared Infrastructure (Wave 0)	_shared/types.ts, _shared/mock-data.ts, _shared/msw-handlers.ts
<!-- REPLACE: DOMAIN::0001::0001 -->		<!-- REPLACE: use-case-group/story-file.stories.tsx -->

Totals:

Category	Count
New files
Modified files
Stories (single-interaction)
Stories (multi-step, 3 variants each)
Description MDX pages

---