Template: Application Conventions

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 — Application Conventions.

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

---

1. Reference Documents

Document	Path	Notes
Entity Data Authority (GEN::ENT-DA)	/documentation/src/content/docs/product/general-behaviors/entity-behaviors/entity-data-authority.md	Generic CRUD behaviors all entity stories inherit
Backend API (<!-- REPLACE: resource -->)
Scope Analysis		Scope decisions (SD-N) and open-question resolutions (OQ-N)
Story Specifications		Per-story play function assertions and file inventory
Existing Storybook

---

2. Shared Infrastructure Registry

File	Built By	Content
use-cases/reference/<!-- REPLACE: domain -->/_shared/types.ts
use-cases/reference/<!-- REPLACE: domain -->/_shared/mock-data.ts
use-cases/reference/<!-- REPLACE: domain -->/_shared/msw-handlers.ts
use-cases/reference/<!-- REPLACE: domain -->/_shared/<!-- REPLACE: page.tsx -->
use-cases/reference/<!-- REPLACE: domain -->/_shared/<!-- REPLACE: other.tsx -->

---

3. MSW Handler Registry

Handler	Route	Method	Added By	Latency	Notes
	<!-- REPLACE: /api/arda/entity/query -->	POST
	<!-- REPLACE: /api/arda/entity/lookup -->	GET
	<!-- REPLACE: /api/arda/entity -->	POST
	<!-- REPLACE: /api/arda/entity/:entityId -->	GET
	<!-- REPLACE: /api/arda/entity/:entityId -->	PUT
	<!-- REPLACE: /api/arda/entity/:entityId -->	DELETE

Error response shape (standard across all endpoints):

{ "ok": false, "status": <!-- REPLACE: HTTP status code -->, "error": "<!-- REPLACE: human-readable message -->" }

---

4. Key Scope Decisions Summary

ID	Summary	Affects	Details
SD-1			scope-analysis.md#sd-1
SD-2			scope-analysis.md#sd-2

---

5. Naming Conventions

5.1 Storybook Title Pattern

All stories in this domain use the following title path format:

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

• Domain Display Name:
• Use Case Group:
• Story Title:

Description MDX pages append /Description to the group path.

5.2 File Naming

Artifact	Pattern	Example
Story file	<scenario-slug>.stories.tsx
Description MDX	<use-case-group-slug>.mdx
Shared component	<component-name>.tsx
Shared types	types.ts	_shared/types.ts
Mock data	mock-data.ts	_shared/mock-data.ts
MSW handlers	msw-handlers.ts	_shared/msw-handlers.ts

5.3 Directory Structure

All story files and shared infrastructure live under:

/ux-prototype/src/use-cases/reference/<!-- REPLACE: domain-slug -->/

The _shared/ prefix on the shared infrastructure directory is intentional: the leading underscore causes Storybook to omit the directory from the sidebar navigation tree.

---

6. Component Patterns

6.1 Decorator Usage (fullAppProviders)

All stories use the fullAppProviders decorator, which supplies:

• The application router context (enables sidebar navigation, usePathname, and deep-link args)
• The MSW service worker (for handler interception)
• The global theme and design-system providers (Tailwind theme tokens, Radix theme context)

const meta: Meta<typeof ComponentName> = {
  title: '...',
  component: ComponentName,
  decorators: [fullAppProviders],
};

6.2 Scoping Queries with within()

When a story renders multiple independent UI regions simultaneously (e.g., a data grid and an open side drawer), use within() to scope queries to the correct container. This prevents “found multiple elements with text X” errors.

const drawer = await canvas.findByRole('dialog');
const drawerPanel = within(drawer);
await expect(drawerPanel.getByRole('heading', { name: '<!-- REPLACE: heading -->' })).toBeVisible();

Re-query the container after mutations that may re-render it — stale element references cause test failures in CI.

Container	How to query	Use for

6.3 Portal-Aware Queries (screen vs. canvas)

Some components render content outside the Storybook canvasElement by portalling to document.body. Use the global screen object for these elements.

Rule: if a query on canvas returns zero results for an element you can see on screen, switch to screen.

Component	Renders in	Correct query
	document.body	screen.findByRole('menuitem', { name: '...' })
	document.body	const el = await screen.findByText('...') then await waitFor(() => expect(el).toBeVisible())

---