Naming Conventions

---
name: naming-conventions
description: Naming and file structure — framework-agnostic with per-framework notes.
---

# Naming Conventions

## Core Rules

| Thing | Convention | Example |
|---|---|---|
| Component | PascalCase | `UserCard`, `OrderSummary` |
| Hook / Composable | camelCase, prefixed `use` | `useOrders`, `useAuthState` |
| Service / class | PascalCase | `OrderService`, `AuthClient` |
| Utility function | camelCase, verb-first | `formatDate`, `parseAmount` |
| Constant | SCREAMING_SNAKE_CASE | `MAX_RETRIES`, `API_BASE_URL` |
| CSS class (BEM) | kebab-case | `order-card__title--active` |
| CSS custom property | kebab-case, prefixed | `--color-primary`, `--spacing-md` |
| Event handler prop | camelCase, prefixed `on` | `onSubmit`, `onItemSelect` |
| Internal handler | camelCase, prefixed `handle` | `handleSubmit`, `handleItemSelect` |
| Boolean prop/var | prefixed `is`, `has`, `can`, `should` | `isLoading`, `hasError`, `canEdit` |
| Enum / union literal | PascalCase (type) + SCREAMING (value) | `Status.PENDING` |

---

## File Naming

| File type | Convention | Example |
|---|---|---|
| Component file | PascalCase | `UserCard.tsx`, `UserCard.vue` |
| Hook file | camelCase | `useOrders.ts` |
| Service file | camelCase or PascalCase (match class) | `orderService.ts` |
| Test file | same name + `.test` / `.spec` | `UserCard.test.tsx` |
| Style module | same name + `.module.css` | `UserCard.module.css` |
| Index barrel | `index.ts` | only at feature boundary |

**Barrel files (`index.ts`)**: use only at the public boundary of a feature folder. Never create barrels inside a feature just to shorten import paths — they prevent tree-shaking and obscure where code lives.

---

## Folder Structure

Prefer **feature-based** over **type-based** once the project exceeds ~5 components.

```
src/
├── features/
│   └── orders/
│       ├── components/     ← UI components scoped to this feature
│       ├── hooks/          ← composables / hooks scoped to this feature
│       ├── services/       ← API calls, business logic
│       ├── types.ts        ← feature-local types
│       └── index.ts        ← public API of the feature
├── shared/
│   ├── components/         ← reusable across features
│   ├── hooks/
│   └── utils/
└── app/                    ← routing, providers, global layout
```

**Rules**:
- A component in `features/orders` must not import directly from `features/users` — go through `shared/`
- `shared/` components must have zero feature-specific knowledge
- Only promote to `shared/` when a second feature needs it (YAGNI)

---

## Framework Notes

### React
- File extension: `.tsx` for components, `.ts` for everything else
- Co-locate styles, tests, and stories with the component file
- Named exports for components; default export only at route level (Next.js / Remix convention)

### Vue
- Single-file components: `PascalCase.vue`
- Multi-word component names only — avoids clashes with native HTML elements (`UserCard`, not `Card`)
- `composables/` folder for `use*` files; `stores/` for Pinia stores

### Angular
- Follow Angular CLI naming: `feature-name.component.ts`, `feature-name.service.ts`, `feature-name.module.ts`
- One class per file; file name must match the class name in kebab-case
- Suffix every class with its role: `Component`, `Service`, `Pipe`, `Directive`, `Guard`, `Resolver`

### Svelte
- File name is the component name: `UserCard.svelte`
- Stores in `stores/` folder; suffix with `Store` if ambiguous (`cartStore.ts`)

---

## Anti-Patterns

| Anti-Pattern | Problem |
|---|---|
| `data`, `info`, `util`, `helper` as names | Too generic — describe what it does, not that it exists |
| `handleClick` on every button | Describe the intent: `handleAddToCart`, `handleDeleteUser` |
| `isLoading2`, `newValue`, `temp` | Temporary names that survive into production |
| Abbreviations beyond 3 letters | `usr`, `ord`, `cfg` — spell it out |
| Inconsistent casing in the same codebase | Pick a convention and enforce it via linter |
| Deep nesting: `components/ui/base/atoms/Button` | Flatten — depth signals over-engineering |