File Structure

Project Structure

src/
├── app/                  # Next.js App Router pages
│   ├── layout.tsx        # Root layout
│   ├── page.tsx          # Home page
│   ├── docs/             # Documentation pages
│   └── dashboard/        # Application pages
├── components/
│   ├── ui/               # Reusable UI components
│   ├── features/         # Feature-specific components
│   └── layout/           # Layout components
├── content/              # Markdown content files
│   └── docs/             # Documentation content
├── design-system/        # Theme and design tokens
├── hooks/                # Custom React hooks
├── lib/
│   ├── utils/            # Utility functions
│   ├── i18n/             # Internationalization
│   └── docs/             # Documentation utilities
├── styles/               # Global styles and SCSS variables
└── types/                # TypeScript type definitions

Component Structure

Each UI component follows this structure:

src/components/ui/Button/
├── Button.tsx            # Component implementation
├── Button.module.scss    # Styles
├── Button.types.ts       # Type definitions (optional)
├── Button.test.tsx       # Unit tests
└── index.ts              # Barrel export

Naming Conventions

Type	Convention	Example
Components	PascalCase	Button.tsx
Hooks	camelCase with use prefix	useMediaQuery.ts
Utilities	camelCase	formatDate.ts
SCSS Modules	ComponentName.module.scss	Button.module.scss
Tests	ComponentName.test.tsx	Button.test.tsx

Import Aliases

Use path aliases for cleaner imports:

// ✅ Use aliases
import { Button } from '@/components/ui';
import { useMediaQuery } from '@/hooks';
import { cn } from '@/lib/utils';

// ❌ Avoid relative paths
import { Button } from '../../../components/ui';

Barrel Exports

Each component folder has an index.ts for clean imports:

// src/components/ui/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button.types';