web-react-dev

name

web-react-dev

description

Use when designing, implementing, reviewing, debugging, testing, or shipping React web client features, including component structure, routing, state ownership, API/data fetching, forms, browser behavior, accessibility, performance, build/deploy, and rendered browser verification. Product-agnostic; use miniapp-product-dev for WeChat/Alipay/Douyin/Baidu mini-programs, app-cross-platform-dev for Flutter/React Native/Android/iOS apps, product-ui-ux-design for UI/UX rules, backend skills for services, and testing-strategy for test-layer planning. Triggers also include "用 React 实现这个前端", "React 组件怎么写", "React 写一个", "Tailwind 怎么写", "Next.js / Vite 项目配置", "重构这个 React 组件/页面(局部)", "refactor a React component/file".

Web React Dev

Use this skill for React web client engineering. It covers browser-rendered React applications, React components, routing, data fetching, forms, frontend API integration, accessibility, performance, build, and deploy checks. It does not own mini-program host behavior, Flutter, native mobile, backend service design, or visual design system rules.

Routing

• Use product-rd-workflow first when the work spans product, design, architecture, implementation, testing, review, and release.
• Use product-ui-ux-design before or alongside coding for interaction model, layout, visual hierarchy, density, states, and UI acceptance.
• Use miniapp-product-dev for WeChat/Alipay/Douyin/Baidu mini-program pages, host-platform APIs, developer tools, review submission, and release. For React/H5 embedded inside a mini-program webview, this skill owns the React page while miniapp-product-dev owns the mini-program shell, bridge, host capabilities, and review/release evidence.
• For Taro projects (React syntax compiled to mini-program runtime): this skill owns the React layer (component decomposition, hooks, state ownership, effect discipline, accessibility primitives) and the pure shared layer in the repo's established shared module: DTOs, types, validators, pure mapping functions.
  • miniapp-product-dev owns Taro lifecycle hooks (useReady/useLoad/useDidShow/useDidHide), Taro.* runtime APIs, platform branching (process.env.TARO_ENV, conditional compilation, platform-specific files), subpackage configuration, host capability adapters, multi-target build invocation, host review/release, and rendered mini-program evidence.
  • Shared runtime adapters that mini-program targets consume are co-owned with a named final-decision owner per adapter, recorded in the repo. The adapter list and the miniapp acceptance-gate enumeration are canonical in miniapp-product-dev (the Shared runtime adapters consumed by mini-program targets row under ## Sibling Boundary With web-react-dev); that gate is blocking and its miniapp contract tests must pass before mini-program targets import the adapter. Web sets browser semantics and cannot merge an adapter change that is browser-safe but mini-program-unsafe. Do not re-add a fixed kill-switch dimension list here: the owner's safety contract names the property (fail-closed flag evaluation) and its release contract makes each host platform's gray-release mechanism its own contract, so the dimensions a given adapter needs come from that platform's contract, not from a list on this side. Before merging an adapter change, the merge record must carry the canonical row's gate token and a passing miniapp-contract run recorded on the change under merge (rule canonical in that row); a merge record without the token, or asserting mini-program-safety without the contract run, is a violation.
  • When shared code must run in both web and mini-program targets, keep react-dom, DOM mutation, browser observers (IntersectionObserver/ResizeObserver/MutationObserver), RAF/layout APIs, and other browser globals out of the shared layer; use Taro cross-platform equivalents at the consumer side.
• Use app-cross-platform-dev for Flutter, React Native, native Android, native iOS, app store release, and device-native capability work.
• Use Go or Python backend skills for API/service ownership, persistence, auth services, queues, and server contracts.
• For backend HTTP integrations, preserve current client wire behavior unless an explicit consumer-migration decision exists. Classify JSON vs protobuf-backed HTTP using ../platform-service-connectivity/references/protobuf-http-contract-signals.md.
  • First decide whether the client diff touches the HTTP contract or wire behavior. Wire-unchanged UI/component/state work does not need a backend owner round-trip and must not claim backend contract conformance.
  • For unrelated client work, classify the diff with the canonical gate. If the surface is out of scope, client work may continue without claiming backend contract conformance.
  • If the canonical gate classifies the diff as in scope, confirm the backend's recorded wire format or route back to the backend contract owner.
  • Routine JSON/OpenAPI changes use the existing API contract record and do not require backend wire-format confirmation when the canonical reference classifies the surface as out of the protobuf wire-format gate.
  • Client API wrappers must consume the backend contract's recorded response envelope per ../platform-service-connectivity/references/http-response-envelope-contract.md: for surfaces on the canonical code/message/data envelope, components and domain state read typed business data from data; other shipped or non-JSON envelopes are consumed per their recorded contract. Read only fields present in the recorded contract — do not infer business fields from unrecorded top-level or fallback shapes — and scatter no duplicate envelope parsing across the client.
  • If backend wire-format evidence is unreachable for an in-scope surface, stop at pending-contract-owner, name the backend owner or owning repo, record the attempted lookup, and set the next escalation path. An assumed-wire-format note never unblocks merge. The blocker clears only when a checkable owner record, quoted prior backend record, or explicit migration decision is available; if no owner responds within the team's review SLA, keep the client change blocked or downscope the touched wire-format surface and record the dropped surface as an open owner-routed gap. Do not claim backend contract conformance or completion for the removed slice.
  • Do not fork IDL or hand-maintain duplicated DTOs in the web repo.
• Use testing-strategy to choose unit/component/API/E2E layers; return here for React-specific implementation.
• Use test-artifact-management when the ask is about generating structured test cases from a Feishu requirements doc or codebase and tracking them in Feishu Bitable before implementation begins.
• Use defect-diagnosis first for failed tests, browser bugs, hydration/rendering issues, flaky UI, API integration symptoms, or production regressions.
• For money, quota, permission, tenant/user data, high-impact AI, repeated submit, async finality, or support-traceable incidents, apply product-rd-workflow high-risk resilience gates before treating the UI as complete.

Core Workflow

Before editing components, routes, state, API clients, styles, configs, or tests, complete enough analysis and planning for the change to be reviewable. Scale the plan to risk: a simple low-risk single-component change can use a short inline plan; multi-file, API-visible, accessibility-sensitive, release, bug-fix, branch/MR, unclear-risk, or high-risk work needs explicit task split, acceptance checks, verification commands, rollback or stop conditions, and named handoffs to testing, miniapp/app, backend, or diagnosis skills before edits. Runtime-visible work additionally consumes the canonical UI/UX delivery contract's Design brief and Test selection Phase 0 before the first implementation edit.

Repo-local agent contracts (AGENTS.md at the repo root and in source directories) are part of the delivery contract: when a change moves a stable boundary, generated surface, workflow, or directory-local rule, update the nearest contract in the same MR and keep coverage in sync per product-rd-workflow's spec / repo-contract sync gate.

When checking a React project against team standards, split findings into deterministic checks and agent review checks. Deterministic checks cover package scripts, typecheck/lint/test/E2E commands, generated API client usage, environment configuration, CI gates, bundle/performance budgets, and request/trace identifier propagation in central clients. Agent review checks cover component ownership, state placement, API contract alignment, finite-value mapping, accessibility/design quality, and whether tests assert behavior instead of only rendering. For the concrete deterministic executor list (ecosystem linter/analyzer rules — eslint-plugin-react-hooks, @typescript-eslint typed rules, dependency-cruiser, tsconfig strict/noUncheckedIndexedAccess) and the shipped client language-basics conformance checkers, see testing-strategy/references/fitness-functions.md §4.1.3 (client language-basics; spec 006). Prefer enabling ecosystem rules over hand-rolling checks.

1. Define the web surface.

   • Route/page, component boundary, URL params/query state, auth/permission state, responsive breakpoints, and browser support.
   • User-visible states: loading, skeleton, empty, partial, success, error, retry, disabled, permission denied, stale/offline, and optimistic update.
   • Data boundary: API client, request cancellation, cache/revalidation, mutation invalidation, pagination, streaming/websocket if used, and typed error mapping.
   • API observability: central clients should attach or preserve request/trace/operation identifiers, measure duration, distinguish cancel from failure, classify upload or long-running requests, and map backend envelopes into typed user-facing errors.
   • Finite-value boundary: generated API enums, backend string codes, URL query values, route params, filters, analytics dimensions, and display labels should flow through one typed client/domain mapping module. Components should use the mapped symbols and label tables instead of scattering raw values such as "US", "CN", "active", or "default" in render, tests, routing, or tracking code. If shared client-domain ownership is unclear, keep a local mapper for the slice, mark temporary duplicate/raw uses with finite-value-debt: <task-ref> <owner> <deadline> <reason>, and record the consolidation owner. Architecture owns the cross-stack semantic decision when the same value must align across web, app, mini-program, backend, storage, and analytics.

2. Analyze the existing web surface.

   • Locate the owning route/page, component tree, state owner, API client, data-fetching layer, styling system, tests, and build scripts before editing.
   • Identify whether state belongs in URL/query params, cache/server state, form state, local component state, browser storage, or global app state.
   • Read repo wrappers first: package manager, dev/build scripts, lint/typecheck/test runners, browser/E2E tools, environment variables, and generated clients.
   • Before generating component-library code: the workspace lockfile resolution is the version authority (npm ls <pkg> / pnpm why / yarn equivalent — a library config file or global CLI can resolve a different release than the workspace); take configuration ground truth (framework, aliases, installed components) from the library's own introspection surface (config file such as components.json, official info CLI/MCP, or the installed package's exports/types); write APIs against the resolved version, never from memory of "current" APIs (prop names and defaults shift across majors). After editing, close with the library's own linter/codemod check on the changed files when one exists (deprecated-usage and a11y rules the generic lint config does not know); for a library major-version migration, follow the official migration checklist + changelog for the exact from→to pair, apply, then re-run the library lint to prove no deprecated usage remains.

Non-Negotiable Rules

• Do not use mocked happy-path component tests as proof that API integration works.
• Do not add Effects for state that can be derived from props/state during render.
• Do not ship user-visible UI without inspecting the rendered browser surface when layout or interaction changed.
• Do not add hidden keyboard traps, icon-only controls without accessible names, or mouse-only critical actions.
• Do not ship configurable shortcuts as scattered keydown handlers; centralize parsing, normalization, scope resolution, reserved-key enforcement, unbind/override behavior, and text-input or modal isolation.
• Do not let server transport errors leak directly into user copy; map them to useful UI states.
• Do not ship high-risk actions with only optimistic UI or generic success/error toasts; users must be able to tell whether the operation is pending, succeeded, failed, retryable, blocked, or needs support.
• Do not treat a frontend API client as done until empty response, invalid JSON, non-2xx envelope, auth expiry, network failure, cancellation, and backend error message extraction are covered at the client or component boundary when relevant.
• Do not scatter backend enum/string literals through React components, URL/query handling, analytics, or tests. Centralize finite-value parsing, display labels, defaults, and unknown-value behavior at the API/client-domain boundary, and keep raw literals only in clearly named boundary conversion tests that cover every known external value plus unknown/default behavior. Migrate existing non-boundary test raw literals for that value in the same pull request or mark each remaining use with finite-value-debt: <task-ref> <owner> <deadline> <reason>, even when the current slice does not introduce a new mapper.
• Do not debug React/browser failures from code inspection alone when a browser reproduction, console output, network trace, screenshot, or focused test can be collected.
• Do not claim a web client fix is complete without naming the browser/rendered verification that was run. If required browser/runtime verification is unavailable after remediation, the status is pre-runtime-test-ready or blocked, not complete.

Reference Loading

• For source provenance, current extraction boundary, and keep/merge/discard decisions, read references/source-evidence-map.md when auditing or re-extracting this skill.
• For embedded H5 inside a host (mini-program web-view / native WebView / payment / vendor app WebView) — H5-author POV: env detection, bridge abstraction, auth-from-host (cookieless), hardware-back integration, safe-area + viewport-fit, host capability degradation, WeChat JSSDK specifics, offline / lifecycle, cross-app navigation, anti-patterns, multi-host smoke matrix — read references/embedded-h5-in-host.md. The host-side contract (web-view component / WebView shell config / native bridge setup) is owned by miniapp-product-dev (mini-program host) and app-cross-platform-dev (native WebView shell).
• For joint extraction from Figma design source AND a React/web monorepo (with package class mapping, design-token cross-validation, deprecation-marker detection), read ../skill-extraction-workflow/references/two-source-extraction-pattern.md. Use when both sources are available; produces aligned design + implementation rules with cross-source token validation.
• For component decomposition, state ownership, effects, routing, forms, and data fetching, read references/react-architecture.md.
• For dense review, report, assignment, resource, assistant, media/capture, or app-hosted workspace state-machine patterns, read references/complex-workspace-patterns.md.
• For browser accessibility, keyboard/focus, responsive behavior, and visual verification, read references/web-ui-quality.md.
• For API integration, caching, error handling, testing, performance, build, and deployment readiness, read references/web-quality-release.md.