Portfolio Development Standards

A comprehensive development guide for building high-performance personal portfolio websites with Next.js 15, React 19, and TypeScript, focusing on Core Web Vitals optimization, accessibility, and exceptional user experience.

When to Use This Skill

Use this skill when:

Project Overview

This skill guides development of a modern portfolio website featuring:

Tech Stack

Architecture Guidelines

File Structure

Follow this standardized structure:

```

src/

├── app/

│ ├── components/

│ │ ├── ui/ # Reusable UI components

│ │ ├── sections/ # Page sections (Hero, Services, etc.)

│ │ ├── Footer.tsx # Social links and contact info

│ │ └── Footer.module.css

│ ├── hooks/ # Custom React hooks

│ ├── utils/ # Utility functions and helpers

│ ├── constants/ # App constants and configuration

│ ├── globals.css # Global styles and CSS variables

│ ├── page.tsx # Main portfolio page

│ ├── page.module.css # Homepage styles and animations

│ └── layout.tsx # Root layout with optimized font loading

└── public/

├── images/ # Optimized images with multiple formats

└── icons/ # SVG icons and favicons

```

Performance Optimization

Core Web Vitals Targets

Optimize for these metrics:

Image Optimization

Always use Next.js Image component with proper configuration:

```typescript

import Image from 'next/image'

const OptimizedHero = () => (

<Image

src="/hero-image.jpg"

alt="Portfolio hero"

width={1200}

height={600}

priority // For above-the-fold images

placeholder="blur"

blurDataURL="data:image/jpeg;base64,..."

/>

)

```

Code Splitting Strategy

Implement dynamic imports for heavy components:

```typescript

import dynamic from 'next/dynamic'

const HeavyComponent = dynamic(() => import('./HeavyComponent'), {

loading: () => <ComponentSkeleton />,

ssr: false // If not needed for SEO

})

```

Bundle Optimization

TypeScript Best Practices

Strict Type Definitions

```typescript

interface ServiceCard {

readonly id: string;

title: string;

description: string;

technologies: readonly Technology[];

performance: {

priority: 'high' | 'medium' | 'low';

renderOrder: number;

};

}

```

Compound Component Pattern

```typescript

const Navigation = {

Root: NavigationRoot,

Item: NavigationItem,

Menu: NavigationMenu

} as const;

// Usage

<Navigation.Root>

<Navigation.Menu>

<Navigation.Item href="#services">Services</Navigation.Item>

</Navigation.Menu>

</Navigation.Root>

```

Accessibility Implementation

WCAG 2.1 AA Compliance

Ensure all interactive elements have proper ARIA labels:

```typescript

<button

aria-label="Toggle navigation menu"

aria-expanded={isOpen}

aria-controls="navigation-menu"

className={styles.menuToggle}

>

<span className="sr-only">Menu</span>

<HamburgerIcon />

</button>

```

Accessibility Checklist

Responsive Design Principles

Mobile-First CSS

```css

/* Base mobile styles */

.container {

padding: 1rem;

}

/* Tablet and up */

@media (min-width: 768px) {

.container {

padding: 2rem;

}

}

/* Desktop and up */

@media (min-width: 1024px) {

.container {

padding: 3rem;

}

}

```

Fluid Typography

```css

.heading {

font-size: clamp(1.5rem, 4vw, 3rem);

}

```

Touch Target Sizes

Ensure all interactive elements are minimum 44px × 44px for mobile usability.

Animation Guidelines

Respect User Preferences

```css

@media (prefers-reduced-motion: reduce) {

*,

*::before,

*::after {

animation-duration: 0.01ms !important;

animation-iteration-count: 1 !important;

transition-duration: 0.01ms !important;

}

}

```

Smooth Transitions

```css

.card {

transition: transform 0.2s ease-out, box-shadow 0.2s ease-out;

}

.card:hover {

transform: translateY(-4px);

box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);

}

```

Loading States and Feedback

Skeleton Screens

```typescript

const SkeletonCard = () => (

<div className={styles.skeleton} aria-label="Loading content">

<div className={styles.skeletonTitle} />

<div className={styles.skeletonText} />

</div>

);

```

Next.js Configuration

Optimized next.config.js

```javascript

const nextConfig = {

experimental: {

optimizeCss: true,

optimizePackageImports: ['react-icons']

},

images: {

formats: ['image/avif', 'image/webp'],

deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],

imageSizes: [16, 32, 48, 64, 96, 128, 256, 384]

},

compress: true,

poweredByHeader: false,

generateEtags: false

};

```

Development Commands

When working with the portfolio project, use:

Performance Monitoring

Web Vitals Tracking

```javascript

import { getCLS, getFID, getFCP, getLCP, getTTFB } from 'web-vitals';

function sendToAnalytics(metric) {

analytics.track('Web Vitals', {

name: metric.name,

value: metric.value,

id: metric.id,

});

}

getCLS(sendToAnalytics);

getFID(sendToAnalytics);

getFCP(sendToAnalytics);

getLCP(sendToAnalytics);

getTTFB(sendToAnalytics);

```

Error Handling

Development Workflow

Code Quality Gates

1. **Pre-commit**: Lint, type-check, format

2. **Pre-push**: Run tests, build validation

3. **CI/CD**: Performance testing, accessibility audit

4. **Deployment**: Lighthouse CI, bundle analysis

Best Practices

Browser Support

Key Principles

1. **Performance First**: Optimize for Core Web Vitals

2. **Accessibility Always**: WCAG 2.1 AA compliance minimum

3. **Mobile-First**: Design and develop for mobile, enhance for desktop

4. **Progressive Enhancement**: Core functionality without JavaScript

5. **Type Safety**: Strict TypeScript for reliability

6. **Component Isolation**: Modular, reusable components

7. **Semantic HTML**: Proper structure and hierarchy

8. **Responsive by Default**: Fluid layouts and typography