```
**Tip:** Use Prettier plugin for automatic Tailwind class sorting.
### Responsive Design
**Mobile-first approach:**
```tsx
// Base classes = mobile, add breakpoints for larger screens
```
**Standard breakpoints:**
```
sm: 640px // Small tablets
md: 768px // Tablets
lg: 1024px // Laptops
xl: 1280px // Desktops
2xl: 1536px // Large screens
```
### Conditional Styling
**For complex conditions, use variants:**
```typescript
const cardVariants = {
default: "border-slate-800 bg-zinc-900",
highlighted: "border-cyan-600 bg-cyan-950",
error: "border-red-600 bg-red-950",
}
```
---
## Directory Structure Standards
### Project Organization
```
app/
├── (auth)/ # Route groups (no URL segment)
│ ├── login/
│ └── register/
├── api/ # API routes
│ └── posts/
│ └── route.ts
├── blog/
│ ├── page.tsx
│ └── [slug]/
│ └── page.tsx
├── @breadcrumbs/ # Parallel routes
│ └── default.tsx
├── layout.tsx # Root layout
├── globals.css
└── page.tsx
components/
├── blog/ # Domain-specific components
│ ├── post-card.tsx
│ └── markdown-renderer.tsx
├── layout/ # Layout components
│ ├── header.tsx
│ └── footer.tsx
└── ui/ # Reusable UI primitives
├── button.tsx
└── card.tsx
lib/
├── api/ # API clients, fetch wrappers
│ └── client.ts
├── types/ # TypeScript type definitions
│ └── post.ts
├── markdown.ts # Business logic modules
├── seo.ts
└── utils.ts # Pure utility functions
public/
├── blog/ # Blog-specific assets
│ └── images/
└── icons/
content/ # Content files (outside app/)
└── blog/
└── posts.md
```
### lib/ Organization
**Modules in lib/:**
- Substantial business logic (markdown.ts, seo.ts)
- API clients and data fetching
- Database connections
- Authentication logic
**Utils in lib/utils.ts:**
- Pure helper functions
- Formatters (formatDate, formatCurrency)
- Validators (isEmail, isValidUrl)
- String manipulations
**Types in lib/types/:**
- Shared TypeScript interfaces
- API response types
- Domain models
- Colocated with their modules when possible
### Component Organization
**By domain/feature:**
```
components/
├── blog/ # Blog-specific
│ ├── post-card.tsx
│ ├── post-list.tsx
│ └── markdown-renderer.tsx
├── auth/ # Auth-specific
│ ├── login-form.tsx
│ └── signup-form.tsx
└── ui/ # Reusable primitives
├── button.tsx
├── card.tsx
└── input.tsx
```
**Not by type:**
```
❌ Don't organize like this:
components/
├── forms/
├── buttons/
├── cards/
└── modals/
```
### Public Assets
**Organize by feature:**
```
public/
├── blog/
│ ├── images/
│ └── thumbnails/
├── icons/
│ ├── social/
│ └── ui/
└── fonts/
```
**Naming conventions:**
- Use descriptive names: `hero-background.jpg` not `img1.jpg`
- Use kebab-case: `user-avatar.png`
- Include dimensions for images: `logo-512x512.png`
---
## TypeScript Best Practices
### Type Safety
**Avoid `any`:**
```typescript
// ❌ Bad
function processData(data: any) {}
// ✅ Good
function processData(data: unknown) {
if (typeof data === 'string') {
// TypeScript knows data is string here
}
}
// ✅ Better: Use specific types
interface PostData {
title: string
content: string
}
function processData(data: PostData) {}
```
### Infer Types from Zod
**Don't duplicate types:**
```typescript
import { z } from 'zod'
// Define schema once
const postSchema = z.object({
title: z.string(),
content: z.string(),
tags: z.array(z.string()),
})
// Infer TypeScript type
type Post = z.infer
// Now you have both runtime validation and compile-time types
```
### Type Imports
**Use type imports for types only:**
```typescript
// ✅ Good: Explicit type import
import type { Metadata } from 'next'
import type { Post } from '@/lib/types/post'
// ✅ Mixed: Regular and type imports
import { getAllPosts } from '@/lib/markdown'
import type { Post } from '@/lib/types/post'
```
---
## Next.js 16 Specific Patterns
### Async Server Components
**Fetch data directly in components:**
```typescript
// app/blog/page.tsx
export default async function BlogPage() {
// Server-side data fetching (no useEffect needed)
const posts = await getAllPosts()
return (
)
}
```
### Static Generation
**Use generateStaticParams for dynamic routes:**
```typescript
// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
const posts = await getAllPosts()
return posts.map(post => ({
slug: post.slug.split('/'), // For catch-all routes
}))
}
export async function generateMetadata({ params }) {
const post = getPostBySlug(params.slug.join('/'))
return {
title: post.frontmatter.title,
description: post.frontmatter.description,
}
}
export default async function PostPage({ params }) {
const post = getPostBySlug(params.slug.join('/'))
return {/* render post */}
}
```
### Client Components
**Minimize 'use client' usage:**
```typescript
// ❌ Unnecessary client component
'use client'
export function StaticCard({ title }) {
return {title}
}
// ✅ Keep as server component (default)
export function StaticCard({ title }) {
return {title}
}
// ✅ Only use 'use client' when necessary
'use client'
import { useState } from 'react'
export function InteractiveCard({ title }) {
const [isOpen, setIsOpen] = useState(false)
return (
setIsOpen(!isOpen)}>
{title}
)
}
```
**When to use 'use client':**
- Using React hooks (useState, useEffect, etc.)
- Using event handlers (onClick, onChange, etc.)
- Using browser APIs (window, localStorage, etc.)
- Using context consumers
### Parallel Routes
**Use for layout composition:**
```typescript
// app/layout.tsx
export default function RootLayout({
children,
breadcrumbs, // From @breadcrumbs parallel route
}: {
children: React.ReactNode
breadcrumbs: React.ReactNode
}) {
return (
<>
{breadcrumbs}
{children}
)
}
```
---
## Common Pitfalls
### 1. Hydration Mismatches
**Problem:** Theme-dependent content renders differently on server vs client.
**Solution:** Use mounted state pattern (see Theming section).
### 2. Image Paths
**Problem:** Incorrect public asset paths.
```typescript
// ❌ Wrong
// ✅ Correct
// Leading slash
```
### 3. Dynamic Route Params
**Problem:** Forgetting slug should be an array for catch-all routes.
```typescript
// app/blog/[...slug]/page.tsx
export async function generateStaticParams() {
// ❌ Wrong
return posts.map(post => ({ slug: post.slug }))
// ✅ Correct
return posts.map(post => ({ slug: post.slug.split('/') }))
}
```
### 4. Over-using Client Components
**Problem:** Adding 'use client' unnecessarily.
**Solution:** Keep components as Server Components by default. Only add 'use client' when you need hooks, events, or browser APIs.
### 5. Date Formats
**Problem:** Inconsistent date formatting.
**Solution:** Use consistent ISO format (YYYY-MM-DD) in data, format for display:
```typescript
// In frontmatter
date: '2025-01-15'
// For display
formatDate(post.frontmatter.date) // "15 ianuarie 2025" (Romanian)
```
---
## Reference
For project-specific architecture and design philosophy, see `CLAUDE.md` at the root of this repository.
This skill focuses on coding conventions and standards. For architecture patterns, markdown processing, and industrial design aesthetic guidelines, refer to the main documentation.