agentic-dev-template/docs/guides/frontend-work-shape.md

Frontend work shape

How frontend work — components, pages, media UI, anything visual — flows through the agent-first workflow. For the broader workflow context see docs/architecture/agent-first-workflow-and-conformance.md.

When this guide applies

You're working on:

• A new or existing component (atom / molecule / organism / template / page)
• A page in apps/web-next or apps/web-tanstack
• A visual or interactive change in @repo/core-ui or features/<feature>/src/ui/
• Storybook stories or visual regression tests

If you're working on a backend use case (factory, repository, manifest entry, event handler, job, realtime channel), use the default backend shape documented in the architecture doc — not this guide.

Where frontend code lives

Surface	Location	When to use
Atomic-design primitives	@repo/core-ui/src/{atoms,molecules,organisms,templates}/	Cross-feature reusables. Generated via pnpm turbo gen core-ui-component.
Feature-scoped UI	features/<feature>/src/ui/	Components and queries specific to a feature. Exported behind the feature's ./ui subpath, never the root barrel (see CLAUDE.md).
Pages	apps/<app>/src/... (Next.js: app/, TanStack: routes/)	Page-level composition. Calls use cases via tRPC controllers; composes components.

Atomic design conventions

Tier rules (enforced by the atomic-tier-import-direction ESLint rule):

Tier	May import from	May NOT import from
atoms	nothing else in core-ui	molecules / organisms / templates / pages / features
molecules	atoms	organisms / templates / pages / features
organisms	atoms, molecules	templates / pages / features
templates	atoms, molecules, organisms	pages / features
pages	all of the above	other pages

Feature-scoped UI (features/<feature>/src/ui/) follows the same tier order internally, and may import from @repo/core-ui at any tier.

Storybook is the spec

Every component has a sibling .stories.tsx. The story file:

• Declares one story per AC bullet (or one variant per AC bullet)
• Uses Storybook's play function for interaction tests where applicable
• Becomes the shared visual contract between human, implementer agent, reviewer agent

Acceptance criteria for a frontend task map directly to story variants:

## Acceptance criteria
- [ ] Renders default variant
- [ ] Renders loading state
- [ ] Renders error state with `message` slot
- [ ] Renders disabled state
- [ ] Click handler fires with event payload

Each bullet becomes one Story export (or one play step on a story).

Test gates

Gate	What it covers	Tool	Latency	When it runs
Component test	behavior, props, interactions	Vitest + Testing Library, or play on stories	<5s	pre-commit, CI
Visual regression	rendered appearance vs. baseline	Playwright screenshot tests	30–120s	CI only; blocks merge on unapproved diffs

The visual regression infrastructure ships as part of the work-system-v1 epic. Until it's in place, frontend work relies on component tests + manual visual review.

Adapted four-step ordering

For a pure UI slice (no backend coupling):

1. Story file — write or extend .stories.tsx; declare the variant for this slice's AC bullet. This is the visual spec — analogous to the manifest entry for backend work.
2. Contracts — props interface in the component file (factory body / render body may still throw not implemented)
3. Tests (red) — component test + the new story (the rendered output is asserted as part of the visual regression baseline, or via Testing Library)
4. Implementation (green) — render JSX, wire interactions, satisfy AC

For a UI slice that consumes a backend use case (e.g. a form component calling auth.signUp), the use case lives in a separate story with its own four steps; the UI story depends-on the use-case story.

Reviewer integration

The reviewer agent for frontend tasks uses two extra inputs beyond the standard diff:

1. Storybook MCP at http://localhost:6006/mcp — query existing components, list variants, fetch the metadata for stories that already exist. The reviewer can list-all-documentation to verify no duplicate component was created.
2. Playwright screenshot CI verdict — the visual diff status from CI. Unapproved diffs trigger reject regardless of code quality.

Reviewer checklist for frontend tasks:

• Every AC bullet has a matching story or play step
• No accidental cross-tier imports (lint already catches this, but verify)
• Component test exercises each AC bullet
• Visual regression diff is either zero or human-approved
• No new component created without checking for an existing equivalent via Storybook MCP

Story split for page-level features

A user-facing feature like "sign up" decomposes into multiple stories under one epic:

Epic: auth-v1
├── Story (user-story):       auth.signUp use case
├── Story (technical-story):  SignUpForm component
│       depends-on: signUp use case
└── Story (technical-story):  /sign-up page
        depends-on: SignUpForm

Each story has its own AC checklist; the depends-on edges enforce sequential dispatch by the orchestrator. The page story typically includes the Playwright E2E test for the full flow.

Conformance for frontend

New ESLint rules added under the frontend work-shape:

• component-must-have-story — every .tsx file exporting a default OR named React component must have a sibling .stories.tsx
• component-must-have-test — every component must have a sibling .test.tsx (or be covered by a play function on its story)
• atomic-tier-import-direction — tier imports must respect the table above
• story-must-cover-all-prop-variants (advisory) — discriminated-union props should have a story per variant

Common pitfalls

• Stale stories. A component changes prop shape; stories don't get updated. The component-must-have-story rule catches missing stories but not stale ones. Reviewer should flag this; visual regression catches the rendered consequence.
• Visual-only changes without story update. A CSS tweak that doesn't change behavior still needs the story to be re-snapshotted. Treat the visual regression diff approval as part of the slice.
• Cross-tier creep. Tempting to import an organism from inside an atom for "convenience". The lint rule blocks it; refactor the shared bit down to an atom or molecule.
• Duplicate components. An agent creates a Button in a feature's ui/atoms/ when one already exists in core-ui. Reviewer queries Storybook MCP for Button before approval; if duplicated, rejects.

Open items (filled in as we ship)

• Playwright screenshot infrastructure — exact setup, baseline storage, approval flow
• Visual regression PR check — GitHub workflow + diff hosting
• Storybook test integration (test:stories) — current status and what we extend