Starting a React web project
Read web-craft first; its rules apply here. The project's existing decisions win over every default below.
1. Intake
Read what is already given: product description, existing repo, pages, design system, STACK.md, DESIGN.md, API
contracts. Then fill the gaps with references/intake.md: surface type (landing, editorial, catalogue, consumer
app, admin, customer portal or a mix), primary user and action, content or operation density, devices, SEO needs,
languages now and later, RTL, auth, backend (Node.js, third-party API, CMS, mock or static).
Ask only what changes a product or architecture decision. State the rest as assumptions.
2. Decide the technical profile
Write each decision with a one-line reason. Do not generate every screen before the direction is chosen.
| Decision | Default and where the reasoning lives |
|---|---|
| Framework and rendering | Public, SEO or CMS-heavy, multilingual → Next.js App Router. Behind a login and highly interactive → React + Vite or the existing Next.js. Simple static surface → the simplest thing that works. references/framework-choice.md |
| UI kit | Distinctive branded product → shadcn/ui. Table/form-heavy admin → Ant Design. Material-style product or MUI already in use → Material UI. Existing system → keep it. One main kit per app surface. references/kit-choice.md |
| Styling | Follows the kit: shadcn → Tailwind (required by shadcn); Ant Design or MUI → the kit's theme, plus CSS Modules for custom pieces; custom or editorial → CSS Modules. Never mix Tailwind and CSS Modules as equal systems on one surface. references/styling-choice.md |
| i18n | Next.js → next-intl; Vite → i18next + react-i18next. Locale registry, fallback, URL policy and catalogue loading are decided on day one. references/i18n-setup.md |
| Motion | CSS transitions for simple state; Motion for React when mount/unmount, layout or orchestration is needed. Duration and easing tokens; reduced motion handled in one place. references/motion-setup.md |
| Forms and data | react-hook-form + Zod; TanStack Query or the framework's data model; keep what exists. |
| Theme | Light/Dark/System for interactive products; a single theme can be a product decision for a branded marketing site. |
| Tests | Typecheck, lint (with eslint-plugin-web-craft and eslint-plugin-jsx-a11y), unit/component tests where behaviour lives, Playwright for critical flows. |
| Language and tools | Strict TypeScript, Yarn pinned per project, one lockfile. |
Verify the current stable versions of every chosen package from official sources on the day, pin versions that
work together, and record them in STACK.md. Never copy version numbers from memory or from this skill.
3. Write the project documents
STACK.md: framework, rendering, kit, styling, i18n engine, data and form tools, versions, environments, scripts. Template:references/stack-template.md.DESIGN.md: product character, the principles taken from references, layout, tokens (colour, type, spacing, radius, elevation, motion), copy rules, motion matrix, i18n notes. Template:references/design-template.md.- The locale list and types come from code config. Documents describe it; they are not a second source of truth.
- Do not create four new documents for every small change.
4. Lay out the project
Feature-based structure, server/client boundaries clear, one API layer, one place for tokens and providers:
references/structure.md.
5. Prove the skeleton
Before building more screens, one small flow must work end to end:
- Locale resolves correctly on the first render (no language flash), switching keeps the route.
- Theme follows the user's choice and the system, without a flash on load.
- A form validates on blur, scrolls to the first error on submit, maps a server error to its field.
- A dialog animates in and out, traps focus and returns it; reduced motion removes the large movement.
- A list or chart shows a skeleton, an empty state and an error with retry.
- Keyboard-only use works; no console or hydration errors.
Then build one representative vertical slice (real-looking content, second language, loading and error states) and check it in a browser at mobile and desktop widths before expanding to other screens.
6. Scripts
dev, build, start (Next.js), typecheck, lint, test, test:e2e. Add analyze when bundle budgets
matter.
Sources
Official links used for these defaults, with the date they were reviewed: references/sources.md. Re-check them for
the version you install.