agent-skills-conventions

Code Conventions

Condensed house style. Adapt to the repo first — read existing layout, aliases, UI layer, and toolchain; match established patterns (core-principles). Full rules with examples live in this skill's references/ directory — read the topic file when detail is needed: core-principles · naming · typescript · components · hooks-state · forms · nextjs · styling · ui-composition · ui-ux · icons · services · data · optimistic-ui · errors · structure · testing

Cheat sheet

Process — inspect the repo before imposing patterns; plan before coding and confirm the approach; be concise; say "I don't know" instead of guessing; simplest code that works; surgical diffs only.

Naming — kebab-case filenames (components too); camelCase vars; booleans is/has/should; handlers handle*, callback props on*; name business meaning, not technical accident. .tsx iff the file contains JSX.

No barrels — never create re-export index.ts files; import directly from the file that defines the symbol.

Components — named arrow-function const exports; no default exports except Next.js file conventions. Props: interface <Component>Props (no I prefix), destructured in the signature. children: React.ReactNode. Compound components as flat named exports from one file (Card/CardHeader — never Card.Header statics). Data-driven rendering: typed as const arrays + .map(), content out of markup.

Flat trees — design for the flattest tree possible: page → section → primitive. No pass-through wrapper components; no prop drilling past one intermediate — compose via children/slot props, fetch/read data where it's used, lift state only to the lowest common owner. Tracing a prop must never take 3–6 file jumps.

Hooks — return an object (never a tuple) exposing status plus only the derived flags call-sites read; booleans derived from status, never stored. Async state is ONE status union ('idle' | 'loading' | 'success' | 'error') in one useState — bare union by default, discriminated-with-payload only when data/errorKey must be tied to the state; never parallel booleans. Failures carry an errorKey, not a message. Server state lives in a query cache (TanStack Query), never useState+useEffect+fetch; live updates are refetchInterval/invalidateQueries/setQueryData from a socket — never a hand-rolled setInterval poll. Context via a createSafeContext factory that throws without a provider.