---
name: erp-kit-app-6-impl-frontend
description: Implement frontend code for applications. Use after deploying the backend with erp-kit-app-5-impl-backend. Triggers when implementing frontend pages, creating React components from screen specs, or when the user mentions implementing frontend, creating pages, or building UI for an application.
disable-model-invocation: true
metadata:
  erp-kit-version: "0.59.0"
---

# Application Frontend Implementation

Implement frontend pages for an application, driven by screen spec documentation and a deployed backend. This phase adapts the existing frontend to match the actual requirements.

## Version Check

Run `npx erp-kit internal measure versions` from the repo root. If `status` is `"violations"`, relay the findings (each states its own fix) and stop; otherwise proceed.

## Progress Logging

Run `npx erp-kit app progress schema` once to load the schema before your first log. Log at every step boundary marked with **Log:** below using `npx erp-kit app progress log --json '<payload>'`. Every payload requires: `v` (always `1`), `sessionId`, `prompt` (user's original request), `event`, `data`, and `conversation` (array of `{role, message}` since last log). See [progress-protocol.md](../erp-kit-shared/references/progress-protocol.md) for the full schema reference.

## Design source: app-shell-patterns (delegated)

This skill does **not** carry its own component / design-system / pattern catalog. All UI building guidance — which AppShell components exist and their APIs, design tokens and theming, the page/interaction patterns, and routing/auth/sidebar conventions — is owned by the **`app-shell-patterns`** skill that ships **inside the installed `@tailor-platform/app-shell` npm package**.

That skill is the **authoritative, always-current** catalog. It may contain **more** fundamentals and patterns than any example below shows, and it grows over time as app-shell ships new versions. **Always open its `SKILL.md` to discover the full, current set — never assume the names listed in this file are complete or up to date.**

**Location (relative to the app's `frontend/` directory):**

```
node_modules/@tailor-platform/app-shell/skills/app-shell-patterns/
├── SKILL.md          # AUTHORITATIVE INDEX — lists every fundamental + pattern in THIS installed version
└── references/
    ├── fundamental/  # foundational refs: components, design tokens/theming, graphql, … (read SKILL.md for the set)
    └── patterns/     # one file per pattern slug — families like list-*, detail-*, form-*, interaction-*,
                      #   plus any new patterns this version adds. Discover them from SKILL.md, don't hardcode.
```

**How to use it:** read app-shell's `SKILL.md` index first, then the `fundamental/` references it
points to, then the specific `references/patterns/<slug>.md` for each screen you build — choosing
the slug **from app-shell's index**, not from any fixed list in this file. Cite the slug in code as
described in Phase 3.

## When to Use

- Implementing frontend pages from screen spec docs
- Creating React components for ListView, Form, or DetailView screens
- Building the frontend UI for an application after backend deployment

## Prerequisites

- Deployed backend (from `erp-kit-app-5-impl-backend`)
- `.env` with `VITE_TAILOR_APP_URL` and `VITE_TAILOR_CLIENT_ID`
- `@tailor-platform/app-shell` **≥ 1.3.0** installed in the frontend (ships the `app-shell-patterns` skill)
- Component test toolchain (from `erp-kit init`): vitest, Testing Library, jsdom
- All four tiers of documentation:
  - `README.md` — Application overview
  - `docs/actor/*.md` — Actor definitions
  - `docs/business-flow/*/README.md` + `story/*.md` — Business flows and user stories
  - `docs/screen/*.md` — Screen specifications (ListView, Form, DetailView)

> **Log:** `step.start` with `data: { skill: "erp-kit-app-6-impl-frontend", context: { app: APP_NAME, screens: count } }`

## Workflow

```
ANALYZE SCREENS → GENERATE GRAPHQL SCHEMA → IMPLEMENT PAGES → VERIFY
```

### Phase 1: Analyze Screen Documentation

Read all screen specs (`docs/screen/*.md`) to build a complete picture:

> **Parallelize if possible:** Dispatch one agent per screen spec to extract page structure, fields, actions, and navigation. Each agent reads a single screen doc and returns structured analysis.

1. **Screen types** — Identify each screen as ListView, Form (create/edit), or DetailView
2. **Fields and columns** — Map required columns (ListView), form fields (Form), and detail fields (DetailView) from each spec
3. **Actions** — Identify navigation actions (create, edit, back-to-list) and mutation actions (save, delete, activate/deactivate)

### Phase 2: Generate GraphQL Schema

Run `pnpm generate` in the frontend directory to fetch the GraphQL schema from the deployed backend.

> **Sync barrier:** Schema generation must complete before page implementation. Generated types are shared across all pages.

### Phase 2b: Code Orientation + Load the Design Catalog

Read existing pages under `src/pages/` to understand the local page patterns (ListView, Form, DetailView), component structure, and GraphQL fragment conventions. Keep what applies, adapt what's close, and remove what doesn't fit.

**Load the app-shell catalog (see "Design source" above):**

- Read app-shell's `SKILL.md` index first (`node_modules/@tailor-platform/app-shell/skills/app-shell-patterns/SKILL.md`) — it lists the slug conventions and every fundamental + pattern in the installed version.
- Then read the `fundamental/` references it lists — typically components, design tokens/theming, and GraphQL conventions, but **follow the index for the current set** rather than assuming fixed filenames. These are read once, not per page.
- Routing, authentication, and sidebar conventions also come from the app-shell catalog (and its upstream `@tailor-platform/app-shell` docs) — not from this skill.

### Phase 3: Implement Frontend Pages

> **Barrier step:** Write shared layout and router files before dispatching page agents. These files are shared across all pages and must not be modified by individual page agents.

Run `pnpm lint`, `pnpm typecheck`, and `pnpm gql-tada:check` regularly during implementation. Fix errors before moving on.

Create pages driven by screen spec docs. For each screen, **pick the app-shell pattern, map fields to AppShell components, and cite the pattern:**

1. Open app-shell's `SKILL.md` index and choose the pattern whose **When to use** best fits the screen. Match your screen-spec type to the closest pattern *family* in the index — a **ListView** maps to a `list-*` pattern, a **DetailView** to a `detail-*` pattern, a **Form (create/edit)** to a `form-*` pattern, and sub-flows (confirm dialogs, bulk select, toasts) to `interaction-*` patterns. **These are families, not a fixed list — always pick from the current set in app-shell's index, which may include patterns not named here.** If nothing fits, ask the user rather than inventing a pattern.
2. Read that pattern file under `node_modules/@tailor-platform/app-shell/skills/app-shell-patterns/references/patterns/<slug>.md`.
3. Map every spec field to a component using app-shell's component reference (the `fundamental/` components file named in its index). Use the generated types from Phase 2 for nullability, enum→Select, and FK→Combobox decisions.
4. **Build forms with app-shell's `Form`/`Field` components — they are wired to react-hook-form + Zod** (see app-shell's component reference; this matches the existing `src/pages/` forms). Note: some app-shell form *pattern* examples show a plain `FormData` handler for brevity — prefer the RHF + Zod `Form` component over copying those snippets.
5. Cite the chosen page pattern at the top of the page file — this is the entire design artifact:
   ```tsx
   /* pattern: <slug> */
   ```

> **Parallelize if possible:** Dispatch one agent per screen. Each agent reads ONLY the app-shell pattern file(s) for its screen type plus the app-shell component reference. Each agent writes only to its own directory `src/pages/<screen-name>/`.
>
> **Shared-file guard:** Layout files, router configuration, and generated types are written before dispatch. Page agents must NOT modify shared files.

### Phase 3a: Custom Components (test-first)

Pages that map spec fields onto app-shell components need no unit test.
A **custom component** under `frontend/src/components/` does — write it
test-first:

1. Write the failing `<name>.test.tsx`, co-located with the component.
2. Implement `<name>.tsx` until it passes.

Skip standard UI-library components and vendored `src/components/ui/**`
primitives — they are tested upstream.
Presentational wrappers can opt out with a `/* no-test: <reason> */` marker.

`erp-kit verify` fails with `missing-component-test` when a custom component has
no co-located test.

See the [component testing reference](references/component-testing.md) for the
toolchain, query strategy, and how to mock external dependencies.

### Phase 3b: Implement E2E Page Objects and Specs

After implementing frontend pages, create E2E test infrastructure:

1. **Page objects** — One per screen doc, grouped by domain under `e2e/pages/`
2. **Spec-specific fixtures** — One fixture file per spec file under `e2e/fixtures/` (same basename), extending `user.ts` with test-scoped fixtures for data needed by that spec
3. **Spec files** — One per business flow under `e2e/tests/` (`<flow>.spec.ts`), holding a single `test()` that walks the flow's `## Flow Diagram` main path end to end. Import `test`/`expect` from the spec's own fixture file
4. **Actor fixtures** — Define in `e2e/fixtures/user.ts` with `Actor` type union matching `docs/actor/` filenames

**Read [e2e testing reference](references/e2e-testing.md)** for page object patterns, fixture setup, spec file structure, and sync check rules. (E2E is ERP-specific and stays in this skill.)

### Phase 4: Verify

```bash
cd <app-root>/frontend
pnpm lint
pnpm typecheck
pnpm gql-tada:check
pnpm test          # component unit tests (vitest)
pnpm build
```

Also run `erp-kit verify` **from the repo root** (not `frontend/`) — it discovers
apps under `apps/*`, so from the wrong directory the component-test check silently
finds nothing. It fails if a custom component is missing its test.

```bash
cd <repo-root>
pnpm exec erp-kit verify
```

> **Log:** `validation` with `data: { command: "pnpm lint && pnpm typecheck && pnpm test && pnpm build", status: "pass"|"fail", issues: [] }`

> **Log:** `step.complete` with `data: { status: "pass"|"fail"|"blocked", summary: "<one-line result with page counts>", artifacts: ["<list of created page paths>"] }`

After verification passes, proceed to implementation review with `/erp-kit-app-7-impl-review`.