/web-development

name: web-development
description: Use when users need to implement, integrate, debug, build, deploy, or validate a Web frontend after the product direction is already clear, especially for React, Vue, Vite, browser flows, or CloudBase Web integration.
version: 2.36.1
license: MIT
alwaysApply: false

Sibling skills (local only)

Sibling CloudBase skills ship beside this skill. Use local relative paths such as `../auth-tool-cloudbase/SKILL.md`.

If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do **not** HTTP-fetch remote skill or protocol markdown into the agent context.

**Cross-cutting protocols** (required before code changes or deployments):

• Change Safety Protocol: `../cloudbase-platform/references/protocols/change-safety-protocol.md`
• Deployment Gate: `../cloudbase-platform/references/protocols/deployment-gate.md`

Web Development

Activation Contract

Use this first when

• The request is to implement, integrate, debug, build, deploy, or validate a Web frontend or static site.
• The design direction is already decided, or the user is asking for engineering execution rather than visual exploration.
• The work involves React, Vue, Vite, routing, browser-based verification, or CloudBase Web integration.

Read before writing code if

• The task includes project structure, framework conventions, build config, deployment, routing, or frontend test and validation flows.
• The request includes UI implementation but the visual direction is already fixed; otherwise read `ui-design` first.
• **⚠️ Any task involving interface styling, layout, color scheme, or font selection — before writing the first line of CSS/Tailwind, you MUST load the `ui-design` skill and output a Design Specification.** Skipping this step causes frontend styling to degrade to generic AI template defaults. The `ui-design` skill must be loaded before any visual implementation begins, not retroactively after the user complains about the appearance.

Then also read

• General React / Vue / Vite guidance -> `frameworks.md`
• Browser flow checks or page validation -> `browser-testing.md`
• Login flow -> `../auth-tool-cloudbase/SKILL.md`, then `../auth-web-cloudbase/SKILL.md`
• Official Account JSAPI Pay, Native QR-code Pay, or WeChat OAuth on CloudBase -> `../cloudbase-wechat-integration/SKILL.md` (official docs: `https://docs.cloudbase.net/integration/introduce.md`)
• CloudBase database work -> matching database skill

Do NOT use for

• Visual direction setting, prototype-first design work, or pure aesthetic exploration.
• Mini programs, native Apps, or backend-only services.
• WeChat payment or Official Account OAuth contract details; use `cloudbase-wechat-integration` after identifying the Web surface.

Common mistakes / gotchas

• Starting implementation before clarifying whether the task is design or engineering execution.
• Mixing framework setup, deployment, and CloudBase integration concerns into one vague change.
• Treating cloud functions as the default solution for Web authentication.
• Skipping browser-level validation after a UI or routing change.
• **History mode SPA with CloudBase static hosting**: deploying a single-page app using History mode (React Router / Vue Router) without configuring the static hosting "404 error document" to `index.html`. This causes `NoSuchKey` / 404 errors when users refresh or directly visit any sub-route.
• In an existing application, detouring into UI redesign or broad repo sweeps before patching the current handlers and services.

Engineering constitution (non-negotiable)

These rules override convenience. Treat them as a gate before saying "done".

1. TypeScript — do not silence the type system

• **Do NOT use `any` to bypass type errors.** Not `: any`, not `as any`, not `@ts-ignore`, not `@ts-nocheck`, not `@ts-expect-error` without a written justification. `any` propagates silently and defeats the only compile-time safety net this project has.
• When a type error appears, fix the root cause:
• Missing / wrong library types → install `@types/...`, or narrow the import, or write a precise `interface` / `type` for the shape you actually use.
• Shape is genuinely unknown at the boundary (JSON from an API, `postMessage` payload, `window.*` injection) → type it as `unknown` and narrow with a type guard (`typeof`, `in`, a discriminator field, or `zod` / equivalent).
• Third-party type is wrong → augment via `declare module` in a local `.d.ts`, not `any`.
• Truly dynamic case (e.g. generic event bus) → use a generic `<T>` with a constraint, not `any`.
• `unknown` + narrowing is the acceptable escape hatch. `any` is not.
• If you genuinely cannot avoid `any` for a specific line (extremely rare), leave a one-line comment with **why** and **what would remove it**, so reviewers can audit.
• The same spirit applies to ESLint: do not sprinkle `// eslint-disable` to mute the real signal. Fix the rule violation, or discuss before disabling.

2. Self-verify before claiming done

Before making any non-trivial code or configuration change, you must first follow the Change Safety Protocol in `cloudbase-platform/references/protocols/change-safety-protocol.md` (declare impact → user confirmation → post-edit verification). Before any static hosting publish or custom domain work, complete the checks in `cloudbase-platform/references/protocols/deployment-gate.md`.

Saying "I've implemented it" / "fixed it" / "it should work" without evidence is not acceptable. Before declaring completion, you must actually run the checks and report the result.

**Static / build layer (always, when applicable):**

• `tsc --noEmit` (or `vue-tsc --noEmit`) passes cleanly — zero errors, zero suppressed diagnostics you added.
• `eslint` / project linter passes on changed files.
• The project's build command (`npm run build` / `pnpm build` / `vite build`) completes without n