frontend-foundation

You build frontends that pass strict, automated quality gates. The templates in this skill are a complete, verified reference app. Copy them, then adapt them. Do not write the infrastructure from scratch.

Paths below are relative to this skill's directory, SKILL_DIR: the folder that holds this file. The real files sit behind the symlink in ~/.claude/skills/frontend-foundation.

Ground rules (both modes)

1. The conventions are binding. In a generated project, AGENTS.md is the source of truth. Read it before you write code, and follow it exactly. Every rule names its enforcing check. If a check fails, fix the code. NEVER add eslint-disable, @ts-ignore, --no-verify or a lower coverage threshold. The two existing documented disables are the only exceptions.
2. Read the installed Next.js docs before you touch routing, caching, metadata, images or config. Use node_modules/next/dist/docs/. Next changes faster than your training data. Known breaking points are listed in references/versions.md.
3. Done means every gate passes. Run pnpm lint, pnpm typecheck, pnpm test:coverage, pnpm build:mock, pnpm test:e2e and pnpm lhci. Report real numbers (coverage %, Lighthouse scores, test counts). If a gate fails and you cannot fix it, say which gate failed and show its output.
4. Deterministic work goes to the scripts. Use scripts/scaffold.sh and scripts/new-slice.sh instead of hand-writing boilerplate. They are tested, and they cost nothing in tokens. If /task-splitter is running, scaffolding counts as T0 (inline shell).
5. Never commit or push unless the user asks. Never write real secrets. Only .env.example is committed.

Mode new: scaffold a product

1. Collect inputs. If the request does not already give them, ask once with AskUserQuestion:
   • product title and a kebab-case package name
   • a one-line description
   • the main entities (nouns) and the main user actions (verbs)
   • the API base URL, or "mock for now"
   • the target directory (default ~/Desktop/<name>)

2. Scaffold.

   bash SKILL_DIR/scripts/scaffold.sh <target> --name <kebab> --title "<Title>" --description "<line>"

   The script:

   • checks Node (22.12 or newer) and pnpm
   • copies templates/project, fills the placeholders and sets packageManager
   • installs the latest versions, keeping the pins in references/versions.md
   • adds the shadcn components and fixes their cn import
   • sets up Husky and installs Playwright Chromium

   It refuses to write into a directory that is not empty. Add --no-browsers when Playwright is not needed yet.

3. Verify the baseline before changing anything. Run pnpm lint && pnpm typecheck && pnpm test:coverage && pnpm build:mock. The reference app must be green before you add anything. If it fails on a fresh scaffold, read references/versions.md first: a new upstream release has usually broken a pin.
4. Replace the reference domain. The reference implements posts in four slices: entities/post, features/create-post, widgets/post-list, and views/posts + views/post-detail. For each real entity:
   • Run bash SKILL_DIR/scripts/new-slice.sh entities <name> --endpoint /<path>, then fill in the types, schema, service, queries, hooks and card. Copy patterns from entities/post.
   • Add MSW handlers and fixtures in mocks/. Extend mocks/server.mjs so dev:mock and E2E keep working without a backend.
   • Add features, widgets and views the same way. Wire the routes in src/app (thin files), plus ROUTES, NAV_ITEMS and the sitemap.
   • Delete the post slices only after their replacements pass, and remove their E2E specs at the same time. Keep the patterns: static generation, prefetch with hydration, the four UI states and Server Action revalidation.
5. Fill in the README.
   • Replace every <!-- FILL ... --> block with real product content.
   • Update the Features list and the env table.
   • Keep it plain: no emojis, no marketing, no filler.
   • Run grep -n "FILL\|__APP_" -r README.md src and confirm it finds nothing.
6. Run every gate (ground rule 3) and fix what fails. Then summarise for the user:
   • what was built
   • the gate results
   • how to run the app
   • what still needs a real backend

Mode feature: add to an existing project

1. Read the project's AGENTS.md. If the project has none, it was not built with this skill: ask whether to adopt the conventions, using references/ as a guide, before you change anything.
2. Place the work in FSD. Decide which layer and slice the work belongs in, using references/architecture-fsd.md. When two slices of the same layer need each other, move the shared part down a layer. NEVER cross-import.
3. Create the skeleton with new-slice.sh (it prints next steps for each layer), or extend an existing slice.

4. Implement with the matching reference:

   Work	Reference
   data fetching and mutations	references/data-layer.md
   loading, error and empty states; toasts; error boundaries	references/ui-states-errors.md
   new routes, metadata, static generation	references/seo-rendering.md
   interactive UI	references/accessibility.md
   env variables, headers, external origins	references/security.md

5. Test as you go (references/testing.md):
   • unit or component tests next to each new file, with an axe check on UI
   • MSW handlers for new endpoints
   • a Playwright spec for every new user flow
   • new pages added to the a11y spec
6. Run every gate (ground rule 3).

Updating the skill itself

When a gate fails because of an upstream change (a new Next, ESLint or Tailwind release):

1. Fix it in a scaffolded project.
2. Port the fix into templates/project.
3. Record the reason in references/versions.md.
4. Re-run a fresh scaffold.sh and every gate.

The skill repo is https://github.com/albkhachikyan/nextjs-frontend-foundation (local clone: ~/Desktop/claude-skills/nextjs-frontend-foundation).

Files

scripts/scaffold.sh            new project from templates/project (deterministic)
scripts/new-slice.sh           FSD slice skeleton that already passes lint, types and tests
templates/project/             the verified reference app (AGENTS.md, configs, src, tests, CI)
references/versions.md         version pins, why they exist, and known upstream pitfalls
references/architecture-fsd.md layers, slices, segments, public API, file naming
references/data-layer.md       axios client, services, React Query, SSR prefetch, mutations
references/ui-states-errors.md skeletons, pending buttons, error boundaries, toasts, 404
references/seo-rendering.md    metadata, static generation and ISR, sitemap, JSON-LD, semantics
references/accessibility.md    WCAG 2.2 AA checklist, shortcuts, focus, testing
references/testing.md          unit, component, E2E and coverage patterns
references/security.md         env split, CSP and headers, supply chain
references/ci-hooks.md         hooks, CI jobs, Lighthouse budgets, troubleshooting