frontend-dev-guidelines

Deep reference guide for complex React patterns in the Marble monorepo. For basic conventions (imports, styling, routes, i18n), see .claude/rules/.

Core Conventions

Components

// Plain function declarations - NOT React.FC or FunctionComponent
// Named exports only - NO default exports
// Props via interface (or type)

interface CaseCardProps {
  caseData: Case;
  onSelect?: (id: string) => void;
  className?: string;
}

export function CaseCard({ caseData, onSelect, className }: CaseCardProps) {
  return (
    <div className={cn('rounded-lg border border-grey-border p-md', className)}>
      <Typo variant="subtitle1">{caseData.name}</Typo>
      <Button onClick={() => onSelect?.(caseData.id)}>Select</Button>
    </div>
  );
}

Query Hook (one file per query)

// /queries/continuous-screening/configuration.ts
import { getContinuousScreeningConfigurationFn } from '@app-builder/server-fns/continuous-screening';
import { useQuery } from '@tanstack/react-query';
import { useServerFn } from '@tanstack/react-start';

export const useContinuousScreeningConfigurationQuery = (stableId: string) => {
  const getContinuousScreeningConfiguration = useServerFn(getContinuousScreeningConfigurationFn);

  return useQuery({
    queryKey: ['continuous-screening', 'configuration', stableId],
    queryFn: async () => {
      const result = await getContinuousScreeningConfiguration({ data: { stableId } });
      return result.config;
    },
  });
};

---

Topic Guides

Read these when working on specific areas:

| Topic | Resource | When to read | |-------|----------|-------------| | Component patterns | component-patterns.md | Writing/editing components | | Data fetching | data-fetching.md | Queries, mutations, loaders, server functions | | Routing | routing-guide.md | TanStack Router routes, breadcrumbs, navigation | | Styling | styling-guide.md | Color tokens, surface tokens, dark mode | | Tables & selects | tables-and-selects.md | Virtual tables, MenuCommand dropdowns | | Forms & modals | forms-and-modals.md | TanStack Form, Modal, Panel | | Common patterns | common-patterns.md | ts-pattern, remeda, icons, toasts, dates | | File organization | file-organization.md | Architecture layers, naming | | TypeScript | typescript-standards.md | Types, Zod v4, model adapters |