TypeScript

Patterns and conventions for all TypeScript code.

Types

• import type {} for type-only imports: import type {FC} from 'react'

Naming, camelCase

All identifiers use camelCase: Zod fields, form name/id/htmlFor, props, state, params.

Exceptions (snake_case OK):

• types/database.ts, mirrors DB column names
• Dynamic template literal names where variable part is already lowercase
• Environment variable names (SUPABASE_URL)

Map snake_case ↔ camelCase at API call boundaries, not in schemas or UI code.

Naming, Descriptive and Self-Documenting

Follow Apple's Swift API Design Guidelines: names should be clear at the point of use, reading like prose. Favor long, descriptive names over short or abbreviated ones. Code should be readable without consulting documentation.

• Functions and methods: imperative verb phrases: calculateProgressPercentageFromCompletedSets, processUserOnboardingProfile
• Parameters: role, not type: totalSeconds not n, emailAddress not s
• Variables: what they hold: restDurationInSeconds, submitButton, weightInputValue
• No abbreviations: spell out unless universally known (url, id, api): animationDurationInMilliseconds not animDur
• No redundant words: availableExercises not exerciseArray, but don't sacrifice clarity for brevity

Exception, React event handlers follow handle{Action}{Element} from the react-code skill (e.g. handleClickSave, handleChangeInput), the {Element} is required, since a bare handleClick or handleChange trips react-doctor/no-generic-handler-names. The descriptive naming guidelines above apply to utilities, hooks, callbacks, and non-event-handler functions.

Read references/naming-conventions.md for extended BAD/GOOD examples of each naming pattern.

Exported Functions, Explicit Return Types

All exported functions must have explicit return types.

Exceptions:

• Route loaders/actions (complex generics)
• React components typed with FC<Props> (return type provided by generic)

// BAD
export const formatDate = (date: Date) => format(date, 'yyyy-MM-dd');

// GOOD
export const formatDate = (date: Date): string => format(date, 'yyyy-MM-dd');

General Rules

• Use type not interface, interfaces support declaration merging, which creates unpredictable behavior; type is consistent and predictable
• Arrays: string[] not Array<string>
• Boolean naming: ^((can|has|hide|is|show)[A-Z]|checked|disabled|required)

Code Patterns

• No switch statements, use if/else chains or object maps; switch requires break, is prone to fallthrough bugs, and is harder to type-check exhaustively
• No TypeScript enums, use as const objects with derived types; enums compile to runtime objects with surprising behavior and don't tree-shake well
• JSX boolean props: always explicit ={true}, makes props grep-able and avoids confusion when a prop is later refactored to a non-boolean type
• Max 3 function parameters, use an options object beyond that; call sites with 4+ positional args are hard to read and argument order mistakes are common
• Inline boolean coercion uses !!x, never Boolean(x); reserve Boolean for point-free use (e.g. array.filter(Boolean)), and coerce per operand in a nullable || chain (!!a || !!b), since !!(a || b) trips @typescript-eslint/prefer-nullish-coalescing
• Prefer undefined over null for GAIA-controlled absence (state, optional fields, internal sentinels); reserve null for external contracts that require it: DOM useRef(null), ref-callback params, React Router data(null), Zod .nullable(), and platform/library APIs that return null

Zod

This project uses Zod 4, in every schema. The deprecated Zod 3 chained forms (.strict(), .email(), single-arg z.record(), .args().returns()) still type-check and lint clean, so nothing flags them, reach for the Zod 4 form deliberately.

• `z.literal([...])` not `z.enum()` for string unions, sort values alphanumerically

Read references/zod.md for the full Zod 3 → Zod 4 migration map (z.strictObject, top-level string formats, z.record arity, function and error shapes). It opens with a standing directive to verify uncertain or suspect Zod forms against the official docs (WebFetched, auto-discovered from node_modules/zod/package.json) rather than trusting v3-era memory.