Portfolio Development Guide

A comprehensive skill for building and maintaining modern portfolio websites with Next.js 15, TypeScript, Tailwind CSS, Three.js animations, multi-theme systems, and complete testing coverage.

What This Skill Does

This skill provides expert guidance for developing professional portfolio websites with:

Instructions for AI Agent

Project Setup & Structure

When working with portfolio projects following this pattern:

1. **Understand the Tech Stack**

- Next.js 15 with App Router and Turbopack for development

- TypeScript for type safety across all components

- Tailwind CSS with custom design system and theme tokens

- Framer Motion for smooth animations

- Three.js + @react-three/fiber for 3D particle effects

- React Hook Form + Zod for form validation

- Jest + React Testing Library for testing (aim for 70%+ coverage)

2. **Follow the Project Structure**

```

src/

├── app/ # Next.js pages (page.tsx, layout.tsx)

├── components/

│ ├── ui/ # Reusable UI components

│ ├── sections/ # Page sections

│ ├── layout/ # Layout components

│ └── blog/ # Blog-specific components

├── hooks/ # Custom React hooks

├── lib/ # Utilities and types

└── content/ # JSON-based content

```

Development Workflow

**CRITICAL**: Before making any code changes, understand the version management system:

1. **Analyze Changes**: Determine if changes are PATCH (bug fixes), MINOR (new features), or MAJOR (breaking changes)

2. **Update Version**: Run appropriate command BEFORE committing:

- `npm run version:patch` for bug fixes

- `npm run version:minor` for new features

- `npm run version:major` for breaking changes

**Quality Gate Checks** (MANDATORY before completion):

Run these three checks in parallel after any code changes:

```bash

npm test && npx tsc --noEmit && npm run lint

```

All three must pass with zero errors before work is considered complete.

Code Quality Standards

**Write Self-Documenting Code**:

**Type Safety**:

**Component Organization**:

**Styling Approach**:

**YAGNI Compliance**:

Testing Requirements

**Comprehensive Testing Strategy**:

**Testing Patterns**:

```typescript

// Component testing

import { render, screen } from '@testing-library/react';

describe('ComponentName', () => {

it('renders correctly', () => {

render(<ComponentName />);

expect(screen.getByRole('button')).toBeInTheDocument();

});

});

// Hook testing

import { renderHook } from '@testing-library/react';

describe('useCustomHook', () => {

it('returns expected value', () => {

const { result } = renderHook(() => useCustomHook());

expect(result.current).toBeDefined();

});

});

```

**Mock Setup** (in setupTests.ts):

Theme System Implementation

**Multi-Theme Support** (6 themes):

**Synthwave/Retrowave Theme**:

Three.js Particle System

**Implementation Guidelines**:

Blog System Architecture

**JSON-Based Content Management**:

**Blog Post Structure**:

```typescript

interface BlogPost {

id: string;

title: string;

description: string;

date: string;

author: string;

category: string;

tags: string[];

content: string;

readTime: number;

}

```

SEO Optimization

**Essential SEO Tasks**:

Content Writing Guidelines

**Natural Language Standards**:

Before Completing Work

**Pre-Commit Checklist**:

Development Commands Reference

```bash

Development

npm run dev # Start dev server with Turbopack

npm run build # Production build

npm run export # Static export

Quality Checks

npm test # Run all tests

npm run test:coverage # Coverage report

npx tsc --noEmit # Type check

npm run lint # Linting

SEO

npm run generate-rss # Generate RSS feed

npm run generate-sitemap # Generate sitemap

npm run generate-seo # Both RSS and sitemap

Versioning

npm run version:patch # Bug fixes (1.0.0 → 1.0.1)

npm run version:minor # Features (1.0.0 → 1.1.0)

npm run version:major # Breaking (1.0.0 → 2.0.0)

```

Examples

Adding a New Component

1. Create component in appropriate directory (ui/, sections/, layout/)

2. Use TypeScript with proper interfaces

3. Apply Tailwind styling with design tokens

4. Write component tests with React Testing Library

5. Export from index if creating ui component

6. Run quality checks before committing

Adding a Blog Post

1. Add entry to `src/content/blog/articles.json`

2. Follow BlogPost interface structure

3. Include proper metadata (title, description, date, tags)

4. Run `npm run generate-seo` to update RSS and sitemap

5. Test blog filtering and search functionality

6. Verify reading progress indicator works

Implementing a New Theme

1. Add theme configuration to next-themes provider

2. Define CSS variables in globals.css under theme class

3. Test theme switching across all components

4. Verify contrast ratios for accessibility

5. Update theme toggle UI if needed

6. Test hydration-safe rendering

Important Constraints

Key Files Reference