Naming conventions

This page is the canonical reference for how things get named in this repo. The patterns — which casing applies to which kind of entity — are held together by code review, not by ESLint. The mechanics of case-only file renames, on the other hand, are now hook-enforced so that you can rename files freely on macOS without silently dropping the change. Following the patterns keeps the codebase searchable, makes diffs predictable, and lowers the cost of jumping between packages.

Quick reference

Casing styles glossary

If you've never had to spell out the difference between these in a code review, here's the cheat sheet.

camelCase

Lower-case first word, capital first letter of every subsequent word, no separators.

Used for: variables, function names, function parameters, props, methods, object keys.

1
const colorScale = "brand"
2
function parseFrontmatter(input: string) { /* ... */ }
3
const isLoading = true
4
const handleSubmit = () => { /* ... */ }

PascalCase

Like camelCase but the first letter is also capitalised. Sometimes called UpperCamelCase.

Used for: React components, classes, types, interfaces, enums, type-only generics.

1
function ColorPalette() { /* ... */ }
2
class HttpClient { /* ... */ }
3
type NavItem = { /* ... */ }
4
interface ColorPaletteProps { /* ... */ }

kebab-case

All lowercase, words separated by hyphens. Sometimes called dash-case or lisp-case.

Used for: non-component file names, directory names, CSS classes, CSS custom properties (with -- prefix), URL segments, npm package names.

generate-nav.ts
color-palette/
bg-primary text-primary-foreground
--color-brand-600
/developers/design-system
@itu/docs-ui

snake_case

All lowercase, words separated by underscores. Rare in this repo.

Used for: external integrations where the destination dictates the casing — Postgres column names, Python scripts, some shell variables.

user_id
created_at

UPPER_SNAKE_CASE

All uppercase, words separated by underscores. Sometimes called SCREAMING_SNAKE_CASE or MACRO_CASE.

Used for: module-level constants, environment variables.

1
const COLOR_SCALES = ["brand", "alt", "sun", "jeans", "gray"] as const
2
const MAX_RETRIES = 3
3
process.env.NEXT_PUBLIC_GATEWAY_URL

File naming in detail

The split between PascalCase and kebab-case for files comes down to one question: is this file primarily a React component?

• Component file → PascalCase.tsx. The filename matches the default-exported component: Button.tsx exports Button. Sub-components used only inside the file stay private; if a file ends up with multiple exports, the one that gives the file its identity sets the name.
• Non-component TypeScript file → kebab-case.ts. Utility modules, scripts, configs, type declarations, MDX components that wrap components but aren't themselves React components — anything that isn't "this is a React component" gets kebab-case.
• Story file → <Component>.stories.tsx. PascalCase, matches its component.
• Test file → <source>.test.ts(x) or <source>.spec.ts(x). Match the source file's casing.
• Type-only file → kebab-case.ts (e.g. types.ts or nav.types.ts). It's not a component.
• Barrel → index.ts.

Renaming a file's casing (macOS gotcha)

macOS's default filesystem is case-insensitive but case-preserving. Combined with git's default core.ignorecase = true, this means a git mv color-palette.tsx ColorPalette.tsx on macOS is silently a no-op — the OS sees the source and destination as the same file, git agrees, and your rename never reaches the remote.

The repo neutralises this in two ways:

1. Automatic git config. pnpm install runs scripts/configure-git.mjs after husky setup, which sets core.ignorecase = false in your local clone. With this set, git tracks case-only renames even though the underlying filesystem doesn't. You don't have to do anything — fresh clones get configured automatically.
2. Pre-commit collision check. .husky/pre-commit rejects commits that contain two paths differing only by case (e.g. both color-palette.tsx and ColorPalette.tsx staged at once). This catches half-finished renames before they reach the remote, where they would silently break on case-sensitive Linux runners.

If you ever need to do the rename manually — on Windows, on a case-insensitive Linux mount, or in a checkout where the auto-config didn't run — use the bulletproof two-step pattern:

1
git mv ColorPalette.tsx _tmp.tsx
2
git mv _tmp.tsx color-palette.tsx
3
git commit

The intermediate name is the trick: it forces a real filesystem-level rename that git can see, regardless of core.ignorecase.

Variable and function naming

A few patterns worth knowing beyond the bare casing rules:

• Booleans read as predicates: prefix with is, has, should, can. Examples: isOpen, hasError, shouldFetch, canEdit.
• Event handlers as props use on prefix: onClick, onSubmit, onSelectionChange.
• Event handlers as locals use handle prefix: handleClick, handleSubmit. The on form is reserved for the prop boundary so the call site reads naturally: <Button onClick={handleClick} />.
• Async functions don't get a special prefix — the return type is the signal. Don't name them fetchUserAsync; just call it fetchUser.
• Single-letter names are only acceptable for tight loops (i, j) or destructuring shorthand. Everywhere else, give it a real name.

Types and interfaces

• Component props always use <ComponentName>Props. This makes it grep-findable and pairs cleanly with the component: search for ButtonProps and you find both the type definition and every consumer that imports it. Examples: ButtonProps, ColorPaletteProps, NavItemProps.
• Discriminated unions use a descriptive PascalCase name: Theme, ApiResponse, BlockType. Avoid generic suffixes like Type or Enum unless they add information.
• Generic type parameters use single letters for simple cases (T, K, V) and descriptive PascalCase prefixed with T for complex cases (TItem, TKey). The single-letter form is preferred when the generic is unconstrained.

Constants

Constants whose value is fixed at module load time and acts as configuration use UPPER_SNAKE_CASE:

1
const COLOR_SCALES = ["brand", "alt", "sun", "jeans", "gray"] as const
2
const SHADES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const
3
const MAX_RETRIES = 3

Local constants inside a function or component stay camelCase — the const keyword already says they don't reassign:

1
function buildSection() {
2
  const sectionTitle = "Contributing"
3
  const items = scanDirectory()
4
  return { title: sectionTitle, items }
5
}

The rule of thumb: if you'd put it in a config file, it's UPPER_SNAKE_CASE. If you'd inline it, it's camelCase.

What about everything else?

A few edge cases that come up often enough to call out:

• Acronyms in PascalCase / camelCase keep only the first letter capital after the first word: HttpClient, not HTTPClient. parseUrl, not parseURL. This makes the boundaries between words readable at a glance.
• Carbon icon names — Carbon ships icons in PascalCase (e.g. <Code />, <DataTable />). Use them as imported, don't rename.
• Payload field names — Payload CMS uses camelCase for field IDs by convention. Match it.
• WordPress meta keys — WordPress uses snake_case for post meta and option keys. Don't fight it; mirror what WP expects.
• Database columns — Postgres column names are snake_case. The Zod schemas at the gateway boundary translate to camelCase for the JS side.

Related

• Commit messages — the format your commit subject follows is its own little convention.
• Branch naming — <type>/<kebab-case> for branches, mirroring the file convention.