Skip to content
Skills Library
Programming · Building & coding

frontend-engineer

/frontend-engineer

Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.

Repository
Botss ↗
Licence
MIT
Last repository change
29.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.

Original author description

Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.

How it works

  1. 1. Before you build
  2. 2. Server and client components
  3. 3. Data: one path per job
  4. 4. Auth and the session cookie
  5. 5. Security rules
  6. 6. UI quality
  7. 7. Testing
  8. 8. Verify before handoff
  9. 9. Avoid
  10. Frontend review-ready checklist
Original SKILL.md headings · 119 lines, 2,046 words
SKILL.md preview
---
name: frontend-engineer
description: Use for the Botss frontend agent building Next.js App Router screens in TypeScript and Tailwind v4 - pages, components, forms, data fetching through the typed API client, Server Actions, auth-aware rendering, loading, empty and error states, and frontend tests. Trigger for any task with role frontend, any change under frontend/, or any question about implementing a screen from the design spec and API contract.
---

# Frontend Engineer

You build the screens users actually touch. Your work is correct when it matches three sources exactly: the **API contract** (what data exists and in what shape), the **design spec** (how each screen looks, reads, and behaves in every state), and the **PRD acceptance criteria** (what the user must be able to do). You do not invent any of the three. When they disagree or are silent, ask: product to `@pm`, look and copy to `@designer`, data and endpoints to `@tech-lead` (see `team-protocol`).

Follow `engineering-discipline` for test-first work, verification, debugging, and scope. This skill covers what is specific to the frontend.

Stack: Next.js App Router (major version pinned in `architecture.md`; at the time of writing that is 16), React 19, TypeScript in strict mode, Tailwind CSS v4 with the design tokens, Vitest with Testing Library, Playwright for end-to-end (owned by QA). Code lives in `frontend/` using the layout in the architecture doc: routes in `src/app/`, shared components in `src/components/`, the typed API client in `src/lib/api/`.

## 1. Before you build

1. Read the task, then its **Consumes / Produces** block. Your component props and the endpoints you call are promises other agents rely on.
2. Read the screen spec and mockup in `.botss/docs/design/screens/` and the relevant parts of `design/DESIGN.md`. List every state the spec names; each becomes a test or a visible check.
3. Read the endpoint in `contracts/openapi.yaml`, and check the generated types in `src/lib/api/` include it. If the backend for it is not built yet, build against the contract using the stub or mock the plan provides; never against a guessed shape.
4. Find the closest existing page or component and follow its patterns.

## 2. Server and client components

* **Server Components by default.** They fetch data on the server, ship no JavaScript, and keep secrets and API details off the client. Add `'use client'` only to the smallest component that needs state, effects, event handlers, or browser APIs, and keep it a leaf where possible.
* **Only serializable props cross from server to client.** React 19 can serialize plain objects, arrays, primitives, `Date`, `Map`, `Set`, and promises, but not functions (except Server Actions) or class instances. For API data, still pass the ISO strings the API returned: they match the generated types, and formatting in one place keeps server and client output identical, which avoids hydration mismatches.
* **Check the installed major first.** Read `frontend/package.json` and, if the major differs from what you know, the Next.js upgrade guide for that major before writing code. Recent majors changed real APIs: `params`, `searchParams`, `cookies()`, and `headers()` are async (`const { id } = await params`); in Next 16 `middleware.ts` became `proxy.ts` and `next lint` was removed (lint runs `eslint` directly). Do not mix old and new patterns.
* **Route segment files.** Give each route segment the files it needs: `loading.tsx` (skeleton matching the layout), `error.tsx` (client component with a retry), `not-found.tsx` (paired with `notFound()` calls). Wrap independently slow sections in `<Suspense>` with a skeleton so the rest of the page renders first.
* **Caching is explicit.** Since Next 15, `fetch` is not cached by default. Decide per call: user-specific data stays uncached; shared, rarely changing data can use `next: { revalidate, tags }`. After a mutation, call `revalidateTag` or `revalidatePath` for what changed.

## 3. Data: one path per job

| Job | Use | Why |
|---|---|---|
| Read data for a page | Server Component calls the typed API client | No client waterfall, no loading flash, no API exposure |
| Create, update, delete from a form | Server Action calling the API client, then revalidate | Works without client JS, one trip, server-side validation |
| Highly interactive client data (live search, infinite list, optimistic toggles) | TanStack Query in a client component, calling the API client | Caching, retries, and optimistic updates without hand-rolled state |
| Filters, sort, pagination cursor, selected tab | URL `searchParams` | Shareable, back button works, survives refresh |
| Form field state | React Hook Form with a Zod schema | Field-level validation and errors without re-render storms |
| Truly global UI state (theme, sidebar open) | Small React context in a client provider | Rare; server data never goes here |

Rules that prevent the most common bugs:
* **Never call `fetch` with hand-written URLs in components.** Use the API client in `src/lib/api/`, which uses types generated from `openapi.yaml` (openapi-typescript or the generator the architecture names). Never hand-edit generated files; if the contract changed, regenerate.
* **Keep JSON snake_case** as on the wire. Use the generated types as they are; do not scatter case conversion.
* **Do not copy server data into global stores or `useState`.** It goes stale and drifts. Derive values instead of storing them.
* **No `useEffect` fetch chains.** Fetch on the server, or use TanStack Query. Effects that fetch, then set state, then fetch again create waterfalls and race conditions.
* **Lists use cursor pagination** per the contract: pass `cursor` from `searchParams`, render "Load more" or "Next" only when `next_cursor` is not null.
* **Errors use the standard envelope.** The API client turns non-2xx responses into a typed `ApiError` with `status`, `code`, `message`, and `fields`. Branch on `code`, show `message` (it is safe for users), and map 422 `details.fields` onto form fields.

Code for all of these: `references/nextjs-patterns.md`.

## 4. Auth and the session cookie

The backend keeps server-side sessions and identifies them with an `httpOnly` cookie named `botss_session`; browser JavaScript never sees a token. The default wiring (the architecture doc may refine it):
* **The browser only talks to the Next.js origin.** `next.config` `rewrites` proxy `/api/:path*` to `API_INTERNAL_URL`, so client-side calls and plain form posts to `/api/...` are same-origin, and the backend's `Set-Cookie` reaches the browser directly.
* **Server Components and Server Actions call `API_INTERNAL_URL` directly** through the API client, which forwards the `botss_session` cookie from `cookies()`.
* **Sign-in and sign-out:** the simplest correct option is a Server Action that calls the backend and copies each `Set-Cookie` from the backend response into `(await cookies()).set(...)` with the same flags; sign-out calls the backend logout and deletes the cookie. Without that copy step, the browser never receives the session cookie. Code: `references/nextjs-patterns.md`, section "Sign-in and sign-out".

Always:
* **Proxy (formerly middleware) checks are not authorization.** The proxy can redirect signed-out users for convenience, but every data access must still be authorized by the backend, and server code must handle 401 and 403 responses (redirect to sign in, or show a "no access" state). Never rely on hiding a link as protection.
* **Never store tokens or user data in `localStorage`.** It is readable by any injected script.

## 5. Security rules

* **Every Server Action is a public POST endpoint.** Anyone can call it with any input. Inside each action: parse input with Zod, confirm the user is signed in, and let the backend enforce ownership. Never pass the raw `FormData` or request body straight through ("mass assignment").
* **Secrets never use the `NEXT_PUBLIC_` prefix.** Those values are inlined into the client bundle at build time. Modules that read secrets start with `import 'server-only'` so an accidental client import fails the build.
* **No `dangerouslySetInnerHTML`** unless the content is sanitized (DOMPurify) and the task requires rich HTML. React escapes everything else for you.
* **Redirects only to known paths.** Never redirect to a URL taken from a query parameter without checking it is a relative path you expect.
* External links that open new tabs use `rel="noopener noreferrer"`.

## 6. UI quality

* **Tokens only.** Use the semantic utilities from the Tailwind v4 theme (`bg-surface`, `text-text-muted`, `bg-primary text-primary-foreground`, `rounded-md`). No raw hex, no arbitrary values like `bg-[#9C4A2F]` or `mt-[13px]`. If you need a value the system lacks, ask the designer; one-offs are how a UI drifts.
* **Every state in the spec is built:** loading, empty, error with retry, success feedback, disabled, long content, and hover, focus-visible, active, disabled per element. A screen that only works with perfect data is not done.
* **Copy comes from the spec**, word for word. Do not invent or reword strings.
* **Semantic HTML first:** `button` for actions, `a`/`Link` for navigation, `label` tied to every input, lists as lists, tables for tabular data, one `h1`, landmarks. A `div` with `onClick` is a bug.
* **Keyboard and screen readers:** everything works with the keyboard, focus is visible, dialogs trap and return focus, icon buttons have accessible names, async results are announced. Details: `references/ui-states-and-a11y.md`.
* **Responsive, mobile first:** build at 375px, then the breakpoints in the spec. No horizontal scrolling at 320px.
* **Images and fonts:** `next/image` with width, height, and meaningful `alt`; fonts via `next/font` mapped onto the theme font variables.
* **No hydration mismatches:** do not render `Date.now()`, `Math.random()`, locale-dependent formatting, or `window` values during server render. Compute on the server and pass down, or render after mount in a client component.

## 7. Testing

Write tests first for anything with logic (see `engineering-discipline`). Setup and patterns: `references/testing-frontend.md`.

* **Component tests** (Vitest and Testing Library) for components with logic or states: query by role and label, interact with `userEvent`, assert what the user sees. Test the loading, empty, and error states, not only the happy path.
* **Unit tests** for formatters, mappers, Zod schemas, and hooks.
* **Mock HTTP at the network boundary** with MSW for client-side requests; do not mock your own components.
* **Async Server Components** are hard to unit test; keep their logic thin (fetch, then pass data to a presentational component) and test the presentational component plus any mapping functions. End-to-end coverage of full pages belongs to QA.
* **Look at it.** Before handoff, run the app and check each state of your screen in a browser at mobile and desktop widths. If Playwright is available, capture screenshots into `.botss/screens/<task-id>/` (a gitignored scratch area the botss CLI collects for the dashboard; do not commit them) and list them in the handoff so the designer can review without rebuilding.

## 8. Verify before handoff

Run the commands the scaffold defined (they are in your task's `verify`), typically: type check (`tsc --noEmit`), lint (`eslint .`), unit and component tests, and `next build`. A successful `next build` catches server-and-client boundary errors, missing `'use client'`, and type errors that the dev server forgives.

## 9. Avoid

* Fetching in client components what a Server Component could fetch.
* Global stores (Zustand, Redux, context) holding server data.
* Re-implementing components the design system or codebase already has.
* Copying markup from the HTML mockup verbatim. Mockups use the CDN and static markup; rebuild with real components and the theme.
* Silently adapting to an API response that differs from the contract. Report it to `@backend` and `@tech-lead`.
* `any`, non-null assertions (`!`) to silence the compiler, and `// @ts-ignore`.
* Disabling ESLint rules (especially `react-hooks/exhaustive-deps`) instead of fixing the cause.

## Frontend review-ready checklist

- [ ] Every acceptance criterion verified in the running app, with evidence in the handoff.
- [ ] Every state in the screen spec implemented and checked (loading, empty, error, success, disabled, long content).
- [ ] Data comes through the typed API client; no hand-written URLs; generated types untouched.
- [ ] `'use client'` only where needed; only serializable props cross the boundary.
- [ ] Server Actions validate with Zod and check the session; 401, 403, 404, 409, and 422 handled in the UI.
- [ ] No secrets in `NEXT_PUBLIC_`; secret-reading modules import `server-only`.
- [ ] Tokens only; no raw hex or arbitrary values; copy matches the spec.
- [ ] Keyboard usable, visible focus, labels on inputs, accessible names on icon buttons.
- [ ] Works at 375px and desktop; no horizontal scroll at 320px; no hydration warnings in the console.
- [ ] Type check, lint, tests, and `next build` pass in this run.
- [ ] Only owned files changed; screenshots in `.botss/screens/<task-id>/` and handoff written.

## References

* `references/nextjs-patterns.md`: API client with error envelope, list page with cursor pagination, Server Action with Zod and auth, form with server error mapping, loading and error files, TanStack Query component.
* `references/ui-states-and-a11y.md`: implementing each UI state and the accessibility patterns for common widgets.
* `references/testing-frontend.md`: Vitest and Testing Library setup, MSW, testing patterns, and what Playwright can and cannot mock.
Files in this package (4)
  • SKILL.md 13 KB
  • references/nextjs-patterns.md 22 KB
  • references/testing-frontend.md 6 KB
  • references/ui-states-and-a11y.md 5 KB

Versions

RepositoryScoreLicence
This page · The-Botss-2/Botss90MIT
wonsukchoi/domain-experts100MIT
pranav8494/team-of-agents100MIT
nelson820125/iforgeai100MIT
nelson820125/iforgeai100MIT
bobbie-xos/superlazydev90MIT

Database snapshot: 13.11.2026 · package version 818f597d84b0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100nextjs
    Next.js 15+ App Router development patterns including Server Components, Client Components, data fetching, layouts, and server actions. Use when creating pages, routes, layouts, components, API route handlers, server actions, loading states, error boundaries, or working with…
  • 100react-frontend
    React, TypeScript, and Next.js patterns for frontend development. Use when building React components, managing state, fetching data, optimizing performance, or working with Next.js App Router. Covers React 18-19, hooks, Server Components, and type-safe patterns.
  • 100react-frontend-patterns
    React 19+, TypeScript, Tailwind CSS, shadcn/ui component patterns, accessibility, forms, state management. Use when building or reviewing React components, pages, or frontend architecture.
  • 90react-typescript
    Use when modifying a frontend that actually uses React and TypeScript, including components, hooks, routing, state, forms, and client-side tests.
  • 100senior-frontend
    Frontend development skill for React, Next.js, TypeScript, and Tailwind CSS applications. Use when building React components, optimizing Next.js performance, analyzing bundle sizes, scaffolding frontend projects, implementing accessibility, or reviewing frontend code quality.
  • 100app-router-helper
    Implement Next.js App Router patterns including Server Components, Client Components, layouts, route organization, and data fetching. Use when building with App Router, organizing routes, or implementing modern Next.js patterns. Trigger words include "App Router", "Server…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.