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.