Example: Story Specification — Pagination

This file excerpts the story specification for the Business Affiliate Pagination story from the Business Affiliate UX project’s story specifications document. It demonstrates the level of detail expected in a single-interaction story specification. Future story specifications should follow this structure.

See the Story Specification template for the full template structure.

---

Context Within the Document

This story appears under section 3.1 Browse and Search (REF::BA::0001) in the full story specifications document. It is one of six stories in the Browse and Search group. The specification assumes that the shared infrastructure (_shared/types.ts, _shared/mock-data.ts, _shared/msw-handlers.ts, _shared/suppliers-page.tsx) is already documented in Section 2.

---

3.1.5 Pagination (BA::0001::0006)

File: browse-and-search/pagination.stories.tsx Storybook title: Use Cases/Reference/Business Affiliates/Browse and Search/Pagination Type: Standard stories (single-interaction)

Stories:

Default

• Renders SuppliersPage with full mock data (28 affiliates, page size 10).
• AG Grid pagination toolbar shows “Page 1 of 3”.
• Initial load displays the first 10 records sorted by name ascending.

Play function assertions:

1. Grid renders with rows present (do not assert exact count — AG Grid buffer rows).
2. Page indicator shows “Page 1 of 3”.
3. User clicks “Next Page” button; grid re-renders with the next 10 records.
4. Page indicator updates to “Page 2 of 3”.
5. First row of page 2 contains a record name from the mock data set that is alphabetically within the second page.
6. User clicks “Previous Page”; grid returns to page 1 records.
7. Page indicator returns to “Page 1 of 3”.
8. User selects page size “50” from the page size dropdown; grid re-renders.
9. Page indicator updates to “Page 1 of 1”.
10. Total row count label reads “28 records”.

Important CI notes:

• Wrap all post-navigation assertions in waitFor() (Pattern 3).
• Do not assert exact row counts (Pattern 2).
• Do not assert toBeVisible() on row content (Pattern 1).

Loading

• Renders SuppliersPage with a 2-second MSW latency override.
• Skeleton/loading indicator appears during initial load.

Play function assertions:

1. Loading indicator (skeleton rows or spinner) is visible immediately.
2. After data loads, grid replaces the loading indicator with data rows.
3. Page indicator displays the correct page count.

---

What Makes This Specification Effective

1. Exact file path and Storybook title — you know exactly where to create the file and what title to use.

2. Initial render state is explicit — you know the mock data count, page size, and sort order before writing any code.

3. Play function steps are ordered and specific — each step names the user action and the expected outcome with enough detail to write assertions.

4. CI stabilization patterns are cited inline — you know which patterns to apply proactively rather than discovering them during debugging.

5. Multiple variants cover different aspects — the Default variant covers happy-path pagination; the Loading variant covers the loading state.

---