Run 8: Acceptance — Project Plan

Overview

Prove the consolidated component library can reproduce dev-witness page layouts using only canary components. This run adds composition stories mapped to product use cases, generates VRT baselines for all new pages, and fills documentation gaps with MDX docs for every component layer.

Repository: ux-prototype at /Users/jmp/code/arda/ux-prototype/ Branch: jmpicnic/component-consolidation Worktree (read-only reference): /Users/jmp/code/arda/callil-consolidation-worktree/

Entry Criteria

#	Criterion	Verification
E1	Run 7 exit gate passed	`plan/run-7-package-api/validate-exit.sh` returns 0
E2	`canary.ts` barrel exports all consolidated components	grep for key exports
E3	`npm run build:lib` passes	Library build verified in Run 7
E4	Branch clean, all Run 7 commits pushed	`git status` clean
E5	Baseline tests pass	`npm run lint && npx tsc --noEmit && npm run test` all green

Artifact Specifications

Artifact	Location	Description
BrowseItems story	`src/use-cases/reference/items/browse-and-search/`	REF::ITM::0001 composition story with play function
ViewItemDetails story	`src/use-cases/reference/items/view-details/`	REF::ITM::0002 composition story with play function
EditItemInline story	`src/use-cases/reference/items/edit-item/`	REF::ITM::0004, GEN::LST::0007 composition story with play function
BrowseSuppliers canary variant	`src/use-cases/reference/business-affiliates/browse-and-search/`	REF::BA::0001 canary variant story
ViewSupplierDetails canary variant	`src/use-cases/reference/business-affiliates/view-details/`	REF::BA::0002 canary variant story
ColumnConfiguration story	`src/use-cases/general-behaviors/list-views/`	GEN::LST::0002 story
SortAndFilter story	`src/use-cases/general-behaviors/list-views/`	GEN::LST::0003, GEN::LST::0004 story
RowSelection story	`src/use-cases/general-behaviors/list-views/`	GEN::LST::0006 story
KitchenSink story	`src/components/canary/organisms/shared/entity-data-grid/`	Developer reference exercising all capabilities
Primitives MDX	`src/components/canary/primitives/`	Layer-level documentation
Atom MDX docs	`src/components/canary/atoms/*/`	Per-component MDX for new atoms
Molecule MDX docs	`src/components/canary/molecules/*/`	Per-component MDX for new molecules
Organism MDX docs	`src/components/canary/organisms/*/`	MDX for organisms missing docs (item-details)
VRT baselines	VRT project config	Baselines for all composition pages

Task List

#	Task	Persona	Depends On	Status	Acceptance Criteria
8.1	Add BrowseItems story	front-end-engineer	E1-E5	Pending	Story at `src/use-cases/reference/items/browse-and-search/` renders Sidebar + AppHeader + ItemGrid (entity-data-grid with item columns) with search, column toggle, multi-select actions. Play function uses step DSL: navigate sidebar, search items, verify filter count, toggle column visibility. Maps to REF::ITM::0001.
8.2	Add ViewItemDetails story	front-end-engineer	8.1	Pending	Story at `src/use-cases/reference/items/view-details/` extends BrowseItems: click row triggers ItemDetails drawer with fields, card preview tab. Play function uses step DSL: click row, verify drawer opens, check field values, switch tabs. Maps to REF::ITM::0002.
8.3	Add EditItemInline story	front-end-engineer	8.1	Pending	Story at `src/use-cases/reference/items/edit-item/` demonstrates inline editing: double-click cell, edit value, blur row, auto-publish with visual feedback (saving state, success). Play function uses step DSL: double-click cell, type new value, click different row, verify save callback. Maps to REF::ITM::0004 and GEN::LST::0007.
8.4	Add BrowseSuppliers canary variant	front-end-engineer	E1-E5	Pending	Story at `src/use-cases/reference/business-affiliates/browse-and-search/` as a canary variant alongside existing extras stories. Renders Sidebar + AppHeader + EntityDataGrid with supplier columns and server-side search. Demonstrates generic factory works for a different entity type. Play function uses step DSL. Maps to REF::BA::0001.
8.5	Add ViewSupplierDetails canary variant	front-end-engineer	8.4	Pending	Story at `src/use-cases/reference/business-affiliates/view-details/` as canary variant. Click row triggers detail panel with tabs. Play function uses step DSL. Maps to REF::BA::0002.
8.6	Add ColumnConfiguration story	front-end-engineer	E1-E5	Pending	Story at `src/use-cases/general-behaviors/list-views/` demonstrates column visibility toggle, reorder, resize, pin. Play function uses step DSL: toggle a column off, verify it disappears; drag to resize; pin a column. Maps to GEN::LST::0002.
8.7	Add SortAndFilter story	front-end-engineer	E1-E5	Pending	Story at `src/use-cases/general-behaviors/list-views/` demonstrates single/multi-column sort and global + per-column filter. Play function uses step DSL: click header to sort, verify order changes; type in filter, verify rows filtered. Maps to GEN::LST::0003, GEN::LST::0004.
8.8	Add RowSelection story	front-end-engineer	E1-E5	Pending	Story at `src/use-cases/general-behaviors/list-views/` demonstrates single select, multi-select, shift-click range, select-all, selection-driven toolbar actions. Play function uses step DSL. Maps to GEN::LST::0006.
8.9	Add KitchenSink developer reference	front-end-engineer	E1-E5	Pending	Story at `src/components/canary/organisms/shared/entity-data-grid/` exercising all promoted capabilities simultaneously: auto-publish + search + toolbar + actions + drag-to-scroll + client-side pagination. Play function uses step DSL to exercise each capability. Serves as developer reference (“here’s everything the grid can do”).
8.10	All play functions use step DSL	front-end-engineer	8.1-8.9	Pending	Every play function in tasks 8.1-8.9 uses the `step()` DSL from the play context. Steps are named, descriptive, and collapsible in the Storybook interactions panel. `storyStepDelay()` used between major interaction steps.
8.11	Generate VRT baselines for all composition pages	front-end-engineer	8.1-8.9	Pending	VRT baselines generated for all new composition stories (BrowseItems, ViewItemDetails, EditItemInline, BrowseSuppliers, ViewSupplierDetails, ColumnConfiguration, SortAndFilter, RowSelection, KitchenSink). Baselines committed. `npx playwright test --project=vrt` passes.
8.12	Playwright MCP comparison against dev-witness equivalents	front-end-engineer	8.11	Pending	Navigate to each composition story and the corresponding dev-witness story in Storybook. Screenshot both. Compare layout, spacing, colors, and interaction patterns. Document discrepancies. Stories should be recognizably similar (not pixel-identical, as component trees differ).
8.13	Add primitives.mdx	technical-writer	E1-E5	Pending	MDX file at `src/components/canary/primitives/primitives.mdx` describing: purpose of the primitives layer, what is included (13 stock shadcn components), shadcn/ui origin, import convention (`@/components/canary/primitives/*`), regeneration instructions (`npx shadcn@latest`). No individual primitive descriptions needed.
8.14	Add MDX for new atoms	technical-writer	E1-E5	Pending	MDX docs for each new atom: badge, button, avatar, card, dialog, drawer, input-group, icon-button, icon-label, read-only-field, search-input, SelectCellEditor. Each MDX includes: component purpose, props table, import path, usage example. Files co-located with component source.
8.15	Add MDX for new molecules	technical-writer	E1-E5	Pending	MDX docs for new molecules: sidebar sub-components (sidebar-header, sidebar-nav, sidebar-nav-item, sidebar-nav-group, sidebar-user-menu), action-toolbar, field-list, overflow-toolbar. Each MDX includes: component purpose, props, import path.
8.16	Add MDX for organisms missing docs	technical-writer	E1-E5	Pending	MDX docs for item-details organism (currently lacks MDX). Verify sidebar, app-header, item-grid, entity-data-grid, entity-data-grid-shim all have MDX. Add any missing.
8.17	Update stale MDX docs referencing old import paths	technical-writer	8.13-8.16	Pending	Search all MDX files for references to `@/components/ui/`, `@/utils`, or other pre-consolidation import paths. Update to canonical paths (`@/components/canary/primitives/`, `@/types/canary/utils`, etc.).

Dependency Graph

E1-E5 (entry criteria)
  |
  +---+---+---+---+---+---+---+---+---+
  |   |   |   |   |   |   |   |   |   |
  v   v   v   v   v   v   v   v   v   v
 8.1 8.4 8.6 8.7 8.8 8.9 8.13 8.14 8.15 8.16
  |   |                           |    |    |
  v   v                           +----+----+
 8.2 8.5                               |
  |                                     v
  v                                   8.17
 8.3
  |
  +---+---+---+---+---+---+
  |
  v
 8.10 (verify all play functions use step DSL)
  |
  v
 8.11 (VRT baselines)
  |
  v
 8.12 (Playwright MCP comparison)

Parallelization: Two parallel work streams:

Stories (front-end-engineer): Items stories (8.1 -> 8.2 -> 8.3), Supplier stories (8.4 -> 8.5), List view stories (8.6, 8.7, 8.8 in parallel), KitchenSink (8.9). Then 8.10, 8.11, 8.12 sequential.
Documentation (technical-writer): MDX tasks (8.13, 8.14, 8.15, 8.16 in parallel), then 8.17.

The two streams are independent until the final exit gate.

Exit Criteria

#	Criterion	Verification
X1	`npm run lint` passes	CI gate
X2	`npx tsc --noEmit` passes	CI gate
X3	`npm run test` passes	CI gate
X4	`npm run build-storybook` passes	CI gate
X5	`npm run test:storybook` passes (all play functions)	CI gate
X6	VRT baselines committed for all composition pages	`npx playwright test --project=vrt` passes
X7	MDX docs exist for all component layers: primitives (1), atoms (12), molecules (8+), organisms (6)	File count check
X8	No MDX files reference old import paths	grep for `@/components/ui/` and `@/utils` in `*.mdx` files
X9	Playwright MCP walkthrough passes (composition stories visually equivalent to dev-witness)	Manual/automated comparison documented
X10	All Run 8 commits on `jmpicnic/component-consolidation`	`git log`

Agent Prompt Templates

front-end-engineer (tasks 8.1-8.12)

You are creating acceptance test stories for the consolidated component library.

Working directory: /Users/jmp/code/arda/ux-prototype/
Branch: jmpicnic/component-consolidation

Key references:
- Use case taxonomy: /Users/jmp/code/arda/documentation/src/content/docs/product/use-cases/
- Test coverage analysis: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/test-coverage.md
- Existing use-case stories: src/use-cases/ (for format reference)
- Dev-witness stories: src/dev-witness/ (visual comparison targets)
- Item-grid organism: src/components/canary/organisms/item-grid/
- Entity-data-grid: src/components/canary/organisms/shared/entity-data-grid/

All play functions MUST use the step DSL:
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);
    await step('Description', async () => { ... });
    await storyStepDelay();
    await step('Next step', async () => { ... });
  };

Start with items stories (8.1-8.3) — these are the highest priority composition
stories. Then suppliers (8.4-8.5) and list view behaviors (8.6-8.8) in parallel.
KitchenSink (8.9) can run alongside.

After all stories are written, verify step DSL compliance (8.10), generate VRT
baselines (8.11), and run Playwright MCP comparison (8.12).

technical-writer (tasks 8.13-8.17)

You are writing MDX documentation for the consolidated canary component library.

Working directory: /Users/jmp/code/arda/ux-prototype/
Branch: jmpicnic/component-consolidation

Key references:
- Primitives analysis: /Users/jmp/code/arda/documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/analysis/primitives.md
- Existing MDX examples: src/components/canary/organisms/sidebar/sidebar.mdx
- Existing MDX examples: src/components/canary/organisms/app-header/app-header.mdx

MDX conventions:
- No markdown tables in MDX files — use HTML <table> elements
- No named HTML entities (&ge;, &times;, &mdash;) — use numeric entities or Unicode
- No bare curly braces in text — use backtick code spans
- Co-locate MDX files with component source files
- Include: component purpose, props overview, import path, usage example

Start with primitives.mdx (8.13) — this is a single file describing the layer.
Then work through atoms (8.14), molecules (8.15), and organisms (8.16) in parallel.
Finally, sweep all MDX files for stale import paths (8.17).

Implementation Output

At run completion, write the following to implementation/run-8-acceptance/:

Artifact	File	Description
Run summary	`summary.md`	What was done, decisions made during implementation, deviations from plan
Byproducts log	`byproducts.md`	Discovered issues, TODOs, observations for later runs
Validation output	`validation-output.txt`	Stdout from `validate-exit.sh` execution
Session log	`session-log.md`	Agent session IDs, timestamps, notable events

Path: documentation/src/content/docs/roadmap/backlog/requested/callil-consolidation/implementation/run-8-acceptance/

Handoff

To Run 9 (canary-refactor Adaptation)

All composition stories render and pass
VRT baselines committed for all new pages
MDX documentation complete for all component layers
Entity-data-grid KitchenSink serves as the developer reference for all capabilities

Key context for Run 9

The canary-refactor stories in src/canary-refactor/ need to be adapted to use the consolidated components from src/components/canary/
The composition stories from Run 8 serve as reference implementations
If Run 9 discovers component gaps, fixes should go into the component library and may require re-running some acceptance checks