Expert guidance for building Next.js 15 portfolio sites with MDX content, TypeScript, and modern React patterns. Includes PIPE method for structured problem-solving.
Expert guidance for building modern portfolio websites with Next.js 15, MDX content management, and best practices for TypeScript, React, and performance.
This skill helps you develop and maintain Next.js 15 portfolio websites with:
1. **Offer PIPE Method**: Ask the user if they want to use the PIPE method for structured problem-solving:
- **Planning**: Create detailed step-by-step plans with scope boundaries and technical requirements
- **Implementation**: Execute the plan while monitoring for deviations
- **Progress Tracking**: Document actual implementation vs. planned changes
- **Evaluation**: Create comprehensive feature documentation in `documentation/` folder
2. If using PIPE, suggest creating a feature branch for organization
3. Always explain reasoning before suggesting changes
1. **TypeScript Configuration**:
- Use strict mode (already configured in project)
- Define proper interfaces and discriminated unions
- Avoid `any` types; use `unknown` when type is truly unknown
- Export types from dedicated type files
2. **React Best Practices**:
- Use functional components exclusively
- Leverage React 19 hooks appropriately
- Implement proper error boundaries and loading states
- Use `React.memo()` only when performance profiling shows benefits
3. **Naming Conventions**:
- camelCase for variables and functions
- PascalCase for components and types
- UPPER_SNAKE_CASE for constants
- kebab-case for file names
1. **Component Design**:
- Keep components small and focused (single responsibility principle)
- Separate concerns: components, hooks, lib utilities, types
- Prefer composition over inheritance
- Create reusable components in `src/components/`
2. **Directory Structure**:
- `src/articles/` - MDX content with frontmatter
- `src/components/` - Reusable UI components
- `src/hooks/` - Custom React hooks
- `src/lib/` - Utility functions and helpers
- `src/types/` - TypeScript type definitions
- `documentation/` - Feature documentation
1. **Adding Content**:
- Place MDX files in `src/articles/`
- Include proper frontmatter with required fields
- Follow the unified articles system schema
- Run content generation scripts before dev/build
2. **Frontmatter Schema**:
- Validate all required fields (title, date, description, etc.)
- Use discriminated unions for article types (project vs blog)
- Ensure type safety throughout the content pipeline
3. **Build Process**:
- Content is statically generated at build time
- No dynamic MDX processing at runtime
- Rebuild/redeploy required for content updates
- Test content generation scripts regularly
1. **Loading Strategies**:
- Implement lazy loading for images using Next.js Image component
- Use code splitting for large components
- Leverage React.lazy() and Suspense for route-based splitting
2. **Animation Performance**:
- Use Framer Motion with proper GPU acceleration
- Implement `will-change` CSS property sparingly
- Optimize animations for 60fps
- Use intersection observers to trigger animations only when visible
3. **Monitoring**:
- Track bundle size with Next.js analyzer
- Monitor Core Web Vitals (LCP, FID, CLS)
- Use React DevTools Profiler for performance bottlenecks
1. **Semantic HTML**:
- Use proper heading hierarchy (h1 → h6)
- Implement landmark regions (nav, main, aside, footer)
- Use semantic elements (article, section, figure)
2. **ARIA & Keyboard Navigation**:
- Add ARIA labels where semantic HTML isn't sufficient
- Implement proper focus management
- Ensure all interactive elements are keyboard accessible
- Test with screen readers
3. **Radix UI Integration**:
- Leverage Radix UI's built-in accessibility features
- Customize components while preserving ARIA attributes
- Test composite components for keyboard navigation
1. **Code Quality**:
- Write meaningful JSDoc comments for complex functions
- Document component props with TypeScript interfaces
- Validate MDX frontmatter schemas
- Run TypeScript compiler checks
2. **Content Validation**:
- Test content generation scripts after schema changes
- Verify all MDX files parse correctly
- Check for broken internal links
- Validate image paths and alt text
3. **Accessibility Testing**:
- Use axe DevTools or Lighthouse for automated checks
- Test keyboard navigation flows
- Verify color contrast ratios (WCAG AA minimum)
- Test with screen readers (NVDA, JAWS, VoiceOver)
When providing solutions:
1. **Explain First**: Always explain the reasoning behind suggested changes
2. **Ranked Options**: Provide 2-3 ranked solutions with pros/cons
3. **Incremental Approach**: Suggest incremental improvements over rewrites
4. **Workspace Focus**: Prioritize workspace improvements over code changes
5. **Context Awareness**: Always consider the build-time content generation workflow
**Adding a New Blog Post**:
1. Create MDX file in `src/articles/blog/`
2. Add required frontmatter (title, date, description, tags)
3. Write content with proper MDX syntax
4. Run content generation script
5. Test locally with `npm run dev`
6. Rebuild for production
**Creating a New Component**:
1. Create file in `src/components/` with PascalCase name
2. Define TypeScript interface for props
3. Implement functional component with proper typing
4. Add JSDoc documentation
5. Export from appropriate index file
6. Test in isolation before integration
**Optimizing Performance**:
1. Run Lighthouse audit to identify issues
2. Check bundle size with Next.js analyzer
3. Profile React components with DevTools
4. Implement lazy loading where beneficial
5. Optimize images and animations
6. Measure improvements with metrics
```typescript
// src/articles/projects/my-project.mdx
---
title: "My Awesome Project"
date: "2024-01-15"
description: "A brief description of the project"
tags: ["react", "typescript", "nextjs"]
featured: true
---
Project content here...
```
```typescript
// src/components/ProjectCard.tsx
interface ProjectCardProps {
title: string;
description: string;
tags: string[];
featured?: boolean;
}
export const ProjectCard: React.FC<ProjectCardProps> = ({
title,
description,
tags,
featured = false,
}) => {
return (
<article className="project-card">
{/* Component implementation */}
</article>
);
};
```
When using the PIPE method, create documentation files like:
```markdown
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/nextjs-15-portfolio-development/raw