Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

frontend-engineer

/frontend-engineer

Buduje ekrany Next.js App Router w TypeScript i Tailwind v4: strony, formularze, pobieranie danych przez klienta API, stany ładowania i błędów oraz testy.

Repozytorium
Botss ↗
Licencja
MIT
Ostatnia zmiana repozytorium
29.10.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 29.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Buduje ekrany Next.js App Router w TypeScript i Tailwind v4: strony, formularze, pobieranie danych przez klienta API, stany ładowania i błędów oraz testy.

Oryginalny opis (EN)

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.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 119 linii, 2 046 słów
Podgląd SKILL.md
---
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.
Pliki w paczce (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

Wersje

RepozytoriumWynikLicencja
Ta strona · The-Botss-2/Botss90MIT
wonsukchoi/domain-experts100MIT
pranav8494/team-of-agents100MIT
nelson820125/iforgeai100MIT
nelson820125/iforgeai100MIT
bobbie-xos/superlazydev90MIT

Migawka bazy z 13.11.2026 · wersja paczki 818f597d84b0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100nextjs
    Opisuje wzorce Next.js 15+ z App Router: Server i Client Components, pobieranie danych, layouty, server actions, stany ładowania, granice błędów, nawigacja i metadane.
  • 100react-frontend
    Podpowiada wzorce frontendu w React, TypeScript i Next.js: komponenty, stan, pobieranie danych, wydajność i App Router.
  • 100react-frontend-patterns
    Przegląda i buduje komponenty React 19 z Tailwind CSS i shadcn/ui, z naciskiem na dostępność, formularze i stan aplikacji.
  • 90react-typescript
    Modyfikuje frontend w React i TypeScript: komponenty, hooki, routing, stan, formularze i testy po stronie klienta.
  • 100senior-frontend
    Buduje komponenty React i Next.js w TypeScript i Tailwind, optymalizuje wielkość bundla i sprawdza dostępność interfejsu.
  • 100app-router-helper
    Pomaga wdrażać wzorce Next.js App Router: Server Components, Client Components, layouty, organizację tras i pobieranie danych.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.