*.tsx

classNames

Notation. Wherever a path appears as

<components>/

,

<utils>/

, or

<types>/

, treat it as a placeholder. Resolve to the project's existing paths and aliases (

src/components

,

app/components

,

~/lib/utils

,

@/types

, etc.). The shape of the convention matters; the exact location does not.

Precedence. These rules apply only where they don't contradict the project's own enforced rules, ESLint / Biome / Prettier configs,

tsconfig

,

CLAUDE.md

/

AGENTS.md

, contributing guides, or stylelint. If a project rule conflicts, the project rule wins; defer to it and (if it makes sense) note the deviation in your PR description.

Framework / runtime. §1-§10 and §13 are framework-agnostic, they apply to any React + TypeScript + Tailwind setup, including a plain Vite + React SPA with no SSR, no RSC, and no router opinions. §11 (SSR-unsafe components), §12 (multilingual), and parts of §14 (RSC / App Router / Server Components / form actions /

next/*

performance helpers) are optional and clearly flagged, skip them on SPAs. The core idioms (atomic hierarchy,

classNames

, variant tokens, dictionaries, polymorphic

as

, slots, React 19

ref

prop, hooks discipline) are universal.

*.tsx

as

• A component must import only from its layer or below:

  atoms ← molecules ← organisms ← layouts ← sections

  . Never go upward.
• Filename pattern:

  PascalCase.tsx

  . If the project uses a category suffix (e.g.

  Button.ui.tsx

  ), keep it consistent across the layer.
• Each folder has an

  index.ts

  barrel re-exporting every

  .tsx

  . Add new files to the barrel in the same change.
• Organisms are typically grouped by domain subfolder (

  organisms/<domain>/

  ) with their own

  index.ts

  .
• Test files live in

  __tests__/

  next to the component (e.g.

  molecules/__tests__

  ).
• Domain-aware components live in

  organisms/

  or below, never in

  atoms/molecules

  .

• Never import

  clsx

  or

  classnames

  from npm in a project that uses this convention. Always use the local

  classNames

  from

  <utils>

  .
• Pass each Tailwind class as its own argument, do not pre-join with spaces.
• Conditional classes: ternary returning a string or

  ""

  /

  false

  .
• Spread arrays produced by Size/Color dictionaries:

  ...SizeDict[size]

  .
• Always pass the user's

  className

  prop last so consumers can override.

className={classNames(
  "inline-flex",
  "items-center",
  "rounded-lg",
  ...SizeDict[size],
  ...ColorDict[variant],
  disabled ? "cursor-not-allowed opacity-50" : "",
  block ? "w-full" : "",
  className          // consumer override, always last
)}

Exception: A component can use a template literal because its class set is trivial. Prefer

classNames

for anything non-trivial, hard limit is 4 css classes applied or more

• Use these tokens for any prop that conceptually maps to color/intent or size.
• Prop type is the derived

  ColorVariant

  /

  SizeVariant

  union (or

  keyof typeof ColorVariants

  if you prefer the key form). Both are equivalent for string-valued const objects.
• Never invent new local size/color string unions when these would fit. If you need a subset, narrow with

  Extract<ColorVariant, "info" | "danger" | "warning" | "success">

  .
• Default values reference the const object:

  size = SizeVariants.medium

  ,

  variant = ColorVariants.primary

  .

Migrating from

enum

? A string-valued

const

object with literal-union type is a drop-in replacement at all call sites that already used

keyof typeof X

, no consumer changes needed.

• Dict name:

  SizeDict

  ,

  ColorDict

  , or

  XColorTypeMap

  , singular, scoped to the component file.
• Values are

  string[]

  so they can be spread (

  ...SizeDict[size]

  ).
• Static base class arrays use

  SCREAMING_CASE

  or

  baseXStyle

  and live above the dict.
• Prefer dictionaries over switches when the lookup is purely keyed; reserve

  switch

  for cases that need to combine bases or share fallthroughs.

• Provide defaults in the destructuring signature:

  variant = "primary"

  ,

  size = SizeVariants.medium

  ,

  bold = false

  .
• Wrap props in

  Readonly<PropsWithChildren<...>>

  when the component does not mutate its props, most components qualify.

• Limit

  as

  to a small set of literals (

  "button" | "a" | "section"

  ). Don't accept arbitrary

  ElementType

  at the prop boundary, that defeats type narrowing on the union.
• Pick a default branch (typically

  "section"

  or

  "div"

  ) via

  as ?? "section"

  and assign to a

  Capitalized

  local typed as

  ElementType

  so JSX accepts it.
• Native attribute interface must match the literal (

  "a"

  ↔

  AnchorHTMLAttributes<HTMLAnchorElement>

  ).

• PascalCase slot prop names (

  Title

  ,

  Actions

  ,

  TitleElement

  ), distinguishes them from primitive props.

• children

  is reserved for the body / primary content.
• For compound components (

  Tabs

  /

  Tab

  ,

  Accordion

  /

  AccordionItem

  ), share coordination state via a React Context scoped to the parent, read with

  useContext

  or React 19's

  use()

  . This is what Radix, Headless UI, React Aria, shadcn/ui, and the React docs all do. Reach for

  Children.map

  +

  cloneElement

  only as a last resort when you specifically need positional info (

  isFirst

  /

  isLast

  ) and the children are guaranteed to be direct, non-wrapped, non-conditional

  <Tab>

  elements.

• Pick one default icon set and use it everywhere. Use a secondary set only when the default lacks the right glyph or the alt set is the right semantic.
• Don't mix paid and free tiers of the same library, pick one source per project.
• Forward icon props through wrappers via

  FontAwesomeIconProps["icon"]

  and

  FontAwesomeIconProps["size"]

  :
  tsx

  interface ButtonIconTooltipProps {
    icon: FontAwesomeIconProps["icon"];
    size?: FontAwesomeIconProps["size"];
  }

• Color via Tailwind

  className

  (

  "text-green-400"

  ,

  "text-red-400"

  ), not the FontAwesome

  color

  prop.
• For loading states use the library's spin variant (e.g.

  <FontAwesomeIcon icon={faSpinner} spin />

  ). Don't combine

  spin

  with

  pulse

  ,

  pulse

  is FA4's legacy 8-step jump and produces a stuttery animation when paired with

  spin

  .
• When an icon-only button needs accessible text, add

  <span className="sr-only">{label}</span>

  .

<components>/atoms/icons/

• Export a zero-prop function returning a single

  <svg>

  JSX literal.
• Are not parameterized by size/color, they're large brand SVGs.
• Are imported from a separate barrel from regular atoms.

• Tailwind only, no CSS Modules, no styled-components, no inline

  style

  except for genuinely dynamic values (e.g.

  objectFit

  , computed colors).
• Pick a theme baseline. If the app is dark-mode-only, default to

  bg-gray-700/800/900

  ,

  text-white

  ,

  text-gray-300/400

  ,

  border-gray-600/700

  and don't add

  dark:

  prefixes. If the app supports both themes, define the baseline in light tokens and pair every surface/text token with a

  dark:

  counterpart.
• Brand color, pick one of two Tailwind-native paths and stick to it:
  1. Use a built-in palette directly (

     indigo

     ,

     emerald

     ,

     blue

     ,

     slate

     , …). Simplest, matches the Tailwind UI / Tailwind Plus convention. Examples in this doc use

     indigo

     .
  2. Extend the theme with a project-named palette via

     theme.extend.colors.<name>

     (v3) or

     @theme { --color-<name>-50…950: … }

     (v4). Common names:

     primary

     ,

     accent

     , or the brand's own name. Avoid

     brand

     only if your design system already uses it for something else.
  Whichever path you pick, primary actions use the

  700

  /

  900

  shades:

  bg-<palette>-700

  /

  hover:bg-<palette>-900

  /

  focus:ring-<palette>-900

  . Don't mix paths within one project.
• Focus states:

  focus:outline-none focus:ring-4 focus:ring-<color>

  .
• Disabled state:

  cursor-not-allowed opacity-50

  .
• Radius:

  rounded-lg

  for buttons/cards/dialogs,

  rounded-full

  for pills/avatars,

  rounded

  for tags.
• Spacing scale anchors: padding

  px-5 py-2.5

  (medium control),

  p-2.5

  (input),

  p-4 md:p-6

  (modal section).
• Typography: prefer a

  Text

  atom over hand-written

  text-2xl font-bold

  on raw

  <h2>

  in new code,

  <Text as="h2" variant="headline" bold>

  .

forwardRef

Applies to any React 19 setup, Vite SPA, Next.js (App or Pages Router), Remix, TanStack Start, etc. Subsections labeled "App Router / RSC only" are framework-specific; skip them on a plain Vite SPA. Everything else (compiler, refs, hooks,

use()

, accessibility, performance, TypeScript) is universal.

Applies only if the React Compiler is actually enabled in the build (

babel-plugin-react-compiler

wired into Babel/SWC, or the Next.js

experimental.reactCompiler

flag, etc.). On a vanilla React 19 project without the compiler, the rules below will produce real perf regressions, keep your existing memoization until the compiler is turned on.

• With the compiler enabled, components and hook outputs are auto-memoized. Stop hand-rolling

  useMemo

  /

  useCallback

  /

  React.memo

  for normal cases, write straightforward code and let the compiler optimize it.
• Only reach for manual memoization when:
  • The compiler bails out (verified via the

    react-compiler-runtime

    warnings or React DevTools "✨" badge absence) and a profiler shows a real regression.
  • You're integrating with a non-compiled third-party that requires referential stability.
• Inline object/array/function props as children are fine under the compiler, don't contort code to hoist them.
• Keep components idempotent (the compiler assumes purity): no mutation of props/state in render, no

  Math.random()

  /

  Date.now()

  in render bodies, no side effects outside event handlers / effects / refs. These purity rules also matter under React 19 Strict Mode regardless of the compiler.

ref

forwardRef

// React 19 idiom, no forwardRef
export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  ref?: Ref<HTMLButtonElement>;
  variant?: ColorVariant;
  size?: SizeVariant;
}

export function Button({
  ref,
  variant = "primary",
  size = SizeVariants.medium,
  className,
  children,
  ...rest
}: PropsWithChildren<ButtonProps>) {
  return (
    <button ref={ref} className={classNames(/* ... */, className)} {...rest}>
      {children}
    </button>
  );
}

• Use callback refs with cleanup (React 19 supports a returned cleanup function) for DOM measurement / external library attach:
  tsx

  <div ref={(node) => {
    if (!node) return;
    const obs = new ResizeObserver(/* ... */);
    obs.observe(node);
    return () => obs.disconnect();
  }} />

• useImperativeHandle

  is still valid when exposing a curated handle, but prefer plain

  ref

  forwarding.

• Treat

  useEffect

  as a last resort. Before reaching for it, ask:
  • Can this be derived during render? (compute from props/state)
  • Can this be done in an event handler?
  • Is it server state? → Use the project's data-fetching layer (TanStack Query, SWR, RSC

    await

    , etc.).
  • Is it shared UI state? → Use the project's existing store (Redux, Zustand, Context). Don't introduce a new mechanism for trivial cases.
• Use

  useId()

  for label/

  htmlFor

  /

  aria-describedby

  /

  aria-labelledby

  pairings. Never roll counters or

  Math.random()

  ids.
• Use

  useSyncExternalStore

  for non-React stores (

  matchMedia

  , custom event buses). Don't reimplement with

  useEffect

  +

  useState

  .
• Use

  useDeferredValue

  /

  useTransition

  to keep input responsive when derivation/list filtering is expensive. Wrap the derivation, not the input.

• useState

  setter accepts a function for derived updates:

  setCount((c) => c + 1)

  , required when the next value depends on the previous and updates may batch.