Next.js 15 MDX Portfolio Development

Development guidelines for building and maintaining a Next.js 15 portfolio website with MDX content management, TypeScript, Tailwind CSS, and Framer Motion.

Project Context

This skill is designed for a Next.js 15 portfolio website with the following characteristics:

Code Style & Standards

When writing or modifying code:

1. **TypeScript**: Use strict mode (already configured). Define proper interfaces and use discriminated unions where appropriate.

2. **Naming Conventions**:

- Variables and functions: `camelCase`

- Components: `PascalCase`

- Types/Interfaces: `PascalCase`

3. **React Patterns**:

- Prefer functional components with hooks over class components

- Follow React 19 best practices

- Use `React.memo()` sparingly, only when performance profiling indicates benefit

Architecture Guidelines

Component Design

1. **Single Responsibility**: Keep components small and focused on one task

2. **Composition over Inheritance**: Build complex UIs by composing smaller components

3. **Separation of Concerns**: Organize code into clear directories:

- `components/` - React components

- `hooks/` - Custom React hooks

- `lib/` - Utility functions and helpers

- `types/` - TypeScript type definitions

Error Handling & Loading States

1. Implement proper error boundaries for component trees

2. Provide meaningful loading states for async operations

3. Handle edge cases gracefully

Performance Considerations

1. Implement lazy loading for images and heavy components

2. Use intersection observers for scroll-triggered features

3. Optimize animations with Framer Motion's performance features

4. Monitor bundle size regularly

Content Management Workflow

MDX Content Structure

1. **Location**: All content files go in `src/articles/`

2. **Frontmatter**: Every MDX file requires valid frontmatter with proper schema

3. **Type Safety**: Use the unified articles system for type-safe content handling

Build-Time Generation

⚠️ **Important**: Content is statically generated at build time

1. Run content generation scripts before `dev` or `build`

2. Any MDX content updates require rebuild/redeploy

3. Test content generation scripts regularly to ensure they work correctly

Content Validation

1. Validate MDX frontmatter schemas before committing

2. Ensure all required fields are present

3. Check that content renders correctly after generation

Accessibility & Semantic HTML

When building components:

1. **Semantic HTML**: Use appropriate HTML5 semantic elements (`<article>`, `<nav>`, `<section>`, etc.)

2. **ARIA Labels**: Add ARIA labels where semantic HTML alone is insufficient

3. **Keyboard Navigation**: Ensure all interactive elements are keyboard-accessible

4. **Focus Management**: Implement proper focus indicators and management

Testing & Quality Assurance

Component Quality

1. Write meaningful component documentation (JSDoc comments)

2. Document props and their expected types

3. Include usage examples for complex components

Content Quality

1. Test content generation scripts with various content types

2. Validate frontmatter schemas regularly

3. Check that MDX content renders correctly across different scenarios

Accessibility Testing

1. Run accessibility audits (e.g., Lighthouse, axe DevTools)

2. Test keyboard navigation flows

3. Verify screen reader compatibility

Performance Monitoring

1. Monitor bundle size with each significant change

2. Run performance audits regularly

3. Check Core Web Vitals metrics

AI Assistant Behavior Guidelines

When assisting with this project, the AI should:

PIPE Method Integration

Before starting problem-solving, **ask the user if they want to use the PIPE method**:

1. **Planning**: Create detailed step-by-step implementation plans with:

- Explicit scope boundaries

- Technical requirements

- Dependencies and prerequisites

2. **Implementation**: Execute the plan step-by-step:

- Monitor for deviations from the plan

- Adjust as needed while documenting changes

3. **Progress Tracking**: Document throughout implementation:

- What was actually implemented vs. planned

- Changes made and reasons why

- Issues encountered and resolutions

4. **Evaluation**: After completion:

- Create comprehensive feature documentation in `documentation/` folder

- Include implementation details for future reference

- Add AI onboarding context for similar features

General AI Behavior

1. **Explain Reasoning**: When suggesting changes, explain why the change is beneficial

2. **Provide Options**: Offer ranked lists of possible solutions with trade-offs

3. **Incremental Improvements**: Suggest incremental improvements rather than complete rewrites

4. **Workspace Focus**: Prioritize workspace improvements (tooling, scripts, documentation) over purely code changes

5. **Build-Time Awareness**: Always consider the build-time content generation workflow when suggesting content-related changes

Common Workflows

Adding New Content

1. Create MDX file in `src/articles/` with proper frontmatter

2. Run content generation script

3. Verify content appears correctly

4. Commit both MDX source and generated files

Adding New Features

1. Consider using PIPE method for complex features

2. Create feature branch for organization

3. Implement with proper TypeScript types

4. Add tests/validation as appropriate

5. Document in `documentation/` folder if significant

Performance Optimization

1. Profile first to identify actual bottlenecks

2. Apply targeted optimizations (lazy loading, code splitting, memoization)

3. Measure impact before and after

4. Document optimization decisions

Notes & Constraints