---

name: Web Development description: Comprehensive standards and best practices for building modern web applications (React, Next.js, TypeScript, Tailwind).

Web Development Skill

This skill defines the mandatory standards, conventions, and workflows for all web development tasks.

1. Core Philosophy & Constraints

• Clean & Scalable: Follow SOLID principles. Prefer functional/discriminative programming.
• Type Safety: strict TypeScript usage is non-negotiable.
• Component-Driven: Build small, focused, reusable components.
• Local Environment: NO Local Docker. Use native runtimes (npm run dev) locally. Dockerfiles are for remote production only.
• Security First:
  • NO hardcoded secrets (.env only).
  • NO exposed APIs without Auth.
  • Scan for key leakage before commits.

2. Technology Stack

• Frameworks: React, Next.js (App Router).
• Language: TypeScript (Strict Mode).
• Styling: Tailwind CSS, Shadcn UI, Radix UI primitives.
• State: React Context (simple), Redux Toolkit (complex/global).
• Validation: Zod.
• Forms: React Hook Form.
• Testing: Jest, React Testing Library.

3. Naming Conventions

Specific Patterns:

• Event Handlers: handleClick, handleSubmit
• Booleans: isLoading, hasError, canSubmit
• Hooks: useAuth, useForm
• Abbreviations: Avoid them. Exceptions: err, req, res, props, ref.

4. Code Style & Implementation

• Formatting: Tabs for indentation. Single quotes. No semicolons (unless needed). 80 char line limit.
• Equality: Always use strict ===.
• Control Flow: Curly braces for multi-line if. Else on same line as closing brace.
• Planning: Write pseudocode before implementation. Document architecture.

5. React & Next.js Best Practices

• Server Components: Default to Server Components. Use 'use client' only for interactivity (hooks, listeners).
• Performance:
  • useCallback/useMemo for expensive ops.
  • React.lazy / Dynamic imports for code splitting.
  • Next/Image for images.
• Key Props: Never use index as key.
• Hooks: Extract logic to custom hooks. Clean up useEffect.

6. TypeScript Rules

• Strict Mode: Enabled.
• Types vs Interfaces: Prefer interface for objects (extensibility). Use type for unions/mappings.
• Generics: Use for flexible actions/utilities.
• No any: Use unknown or strict checks. Use Type Guards.

7. UI & Styling

• Tailwind: Utility-first. Mobile-first (responsive).
• Shadcn UI: Use for consistent base components.
• Theming: CSS variables for colors/spacing. Dark mode via Tailwind/CSS vars.
• Accessibility (A11y):
  • Semantic HTML.
  • Keyboard navigation coverage.
  • ARIA attributes where semantic tags fail.
  • Color contrast compliance.

8. State Management (Redux Toolkit)

• Organization: Use createSlice. Normalize state (flat structure).
• Selectors: Encapsulate access.
• Slices: Feature-based separation (not monolithic).

9. Testing & Quality

• Unit: Jest + RTL. Test behavior, not implementation details.
• Integration: Focus on workflows.
• TDD Requirement (If active): Red -> Green -> Refactor.
• Linting: No eslint-disable. Fix errors immediately.

10. Production (EXPERIMENTAL) & AI

• Environment:
  • Review: NEVER hardcode API URLs. Use NEXT_PUBLIC_API_URL etc.
  • Config: Maintain .env.example.
• Database: Plan for schema migrations. Don't break prod DB.
• AI Models:
  • Priority: Gemini 3.0 > 2.5.
  • Documentation: You MUST create and maintain AI_MODELS.md in the project root.
  • Required Content:

    Service/Feature	Model Name	File Location	Purpose	Est. Cost (per 1k tokens)
    Example: Chat	gemini-3.0-pro	server/services/chat.ts:45	User conversation handling	$0.00025 input / $0.0005 output

  • Update Trigger: Every time you add, change, or remove an AI model call, update this file.

11. API Documentation (Backend)

• Requirement: Every backend API MUST have Swagger/OpenAPI documentation.
• Implementation:
  • Use swagger-jsdoc + swagger-ui-express (Node/Express) or equivalent for your stack.
  • Document ALL routes with: method, path, description, request body schema, response schema, and auth requirements.
• Security Documentation: Each endpoint must specify:
  • Authentication method (JWT, API Key, OAuth, Public)
  • Required permissions/roles
  • Rate limiting (if applicable)
• Location: Serve docs at /api/docs or /swagger.
• Maintenance: Update Swagger docs on every API change.

12. Workflow Triggers

• Backend Logic Detection: If writing DB/Secret logic in a Client Component -> STOP. Suggest decoupling.
• Cross-Stack Verification: If editing Client AND Server in one go -> STOP. Ask for confirmation.

13. Link Integrity

• No Dead Ends: Every link (<a> tag or router navigation) MUST point to a functional destination. 404s are unacceptable.
• Verification: Always verify link targets during implementation and testing. For internal links, ensure the route exists. For external links, ensure the URL is valid.
• Clarification: If the destination of a link is unclear or not yet implemented, ASK THE USER for instructions before proceeding. Do not use placeholder links (e.g., #) in production-ready code without explicit approval.

14. Project Documentation (README.md)

• Requirement: Every project MUST have a README.md file in the root directory.
• Essential Content: The README must include a "Getting Started" or "Setup" section that explains:
  • Prerequisites: Required tools (e.g., Node.js version, npm/yarn).
  • Environment Variables: List of required variables (referencing .env.example).
  • Installation: Commands to install dependencies (e.g., npm install).
  • Development: Commands to run the app locally (e.g., npm run dev).
  • Testing: Commands to run tests (e.g., npm test).
  • Architecture: Brief overview of the project structure and key components.

15. Visual Verification & Rendering

• Mandatory Verification: Frontend work is NOT considered complete until it has been visually verified in a real browser environment.
• Browser Tool: Use the browser tool to navigate to the local development environment (npm run dev) and capture screenshots or videos of the rendered UI.
• Checklist:
  • Rendering: Ensure all components render without errors or layout shifts.
  • Responsiveness: Verify the UI across Mobile, Tablet, and Desktop breakpoints.
  • Dark Mode: If implemented, ensure styles are correct in dark mode.
  • Interactivity: Test hover states, clicks, and form submissions to ensure the UI responds as expected.
• Fail Proof: If the browser tool fails to load the page or rendering is broken, you MUST identify and fix the issue before asking for user review.

16. Interactive Content Discovery

• Proactive Consultation: When building multi-level or complex websites, do not assume the content or purpose of nested pages.
• Mandatory Questions: As you build, proactively ask the user: "Would you like a page that does [X]?" or "How should this nested section behave?"
• Final Design Check: At the conclusion of the primary build-out, you MUST ask the user: "Are there any other pages you think I should design?" to ensure no requirements were missed.