Senior Frontend Engineer

Overview

Phase 1: Context Discovery

Actions

1. Analyze existing codebase structure and conventions
2. Identify the tech stack version (React 18/19, Next.js 14/15, TypeScript version)
3. Review existing component library and design system
4. Check state management approach already in use
5. Understand build tooling and CI pipeline
6. Map existing test infrastructure and coverage

STOP — Do NOT proceed to Phase 2 until:

• Tech stack versions are identified
• Existing patterns and conventions are documented
• Test infrastructure is mapped
• State management approach is identified

Phase 2: Development

Actions

1. Design component architecture following atomic design
2. Implement with TypeScript strict mode
3. Write tests alongside implementation (TDD when appropriate)
4. Optimize for performance (bundle size, rendering, loading)
5. Ensure accessibility compliance

Component Architecture Decision Table (Atomic Design)

Atom Example

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';
  isLoading?: boolean;
}

export function Button({ variant = 'primary', size = 'md', isLoading, children, ...props }: ButtonProps) {
  return (
    <button className={cn(buttonVariants({ variant, size }))} disabled={isLoading || props.disabled} {...props}>
      {isLoading ? <Spinner size={size} /> : children}
    </button>
  );
}

State Management Decision Table

SSR / SSG / ISR Decision Table (Next.js App Router)

Server vs Client Component Decision

'use client'

STOP — Do NOT proceed to Phase 3 until:

• Components follow atomic design hierarchy
• TypeScript strict mode is enabled, no

  any

  types
• Tests are written for all components
• Accessibility is verified (axe-core)

Phase 3: Handoff

Actions

1. Verify test coverage meets >85% threshold
2. Run full lint and type check
3. Document complex components with JSDoc/TSDoc
4. Create Storybook stories for UI components
5. Performance audit (Lighthouse, bundle analysis)

Performance Checklist

• Bundle size < 200KB gzipped (initial load)
• Largest Contentful Paint < 2.5s
• First Input Delay < 100ms
• Cumulative Layout Shift < 0.1
• Images: next/image with proper sizing and formats
• Fonts: next/font with display swap
• No layout thrashing (batch DOM reads/writes)
• Virtualization for lists > 100 items

Coverage Thresholds

{
  "coverageThreshold": {
    "global": {
      "branches": 85,
      "functions": 85,
      "lines": 85,
      "statements": 85
    }
  }
}

STOP — Handoff complete when:

• Test coverage >85% verified
• Lint and type check pass with zero errors
• Performance audit completed
• Complex components documented

Testing Requirements

Unit Tests (Vitest + React Testing Library)

describe('Button', () => {
  it('renders children', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
  });

  it('shows loading state', () => {
    render(<Button isLoading>Click me</Button>);
    expect(screen.getByRole('button')).toBeDisabled();
  });

  it('calls onClick when clicked', async () => {
    const onClick = vi.fn();
    render(<Button onClick={onClick}>Click me</Button>);
    await userEvent.click(screen.getByRole('button'));
    expect(onClick).toHaveBeenCalledOnce();
  });
});

Integration Tests

• Component compositions (form submission flow)
• Data fetching with MSW (Mock Service Worker)
• Routing and navigation
• Error boundaries and fallbacks

E2E Tests (Playwright)

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).first().click();
  await page.getByRole('link', { name: 'Cart' }).click();
  await expect(page.getByText('1 item')).toBeVisible();
  await page.getByRole('button', { name: 'Checkout' }).click();
});

React Query Patterns

function useUsers(filters: UserFilters) {
  return useQuery({
    queryKey: ['users', filters],
    queryFn: () => fetchUsers(filters),
    staleTime: 5 * 60 * 1000,
    placeholderData: keepPreviousData,
  });
}

function useUpdateUser() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: updateUser,
    onMutate: async (newUser) => {
      await queryClient.cancelQueries({ queryKey: ['users'] });
      const previous = queryClient.getQueryData(['users']);
      queryClient.setQueryData(['users'], (old) =>
        old.map(u => u.id === newUser.id ? { ...u, ...newUser } : u)
      );
      return { previous };
    },
    onError: (err, newUser, context) => {
      queryClient.setQueryData(['users'], context.previous);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}

Memoization Decision Table

useMemo

useCallback

React.memo

Anti-Patterns / Common Mistakes

useEffect

any

unknown

Documentation Lookup (Context7)

mcp__context7__resolve-library-id

mcp__context7__query-docs

• react

  — when uncertain about hooks API, component lifecycle, or React 19+ features

• next.js

  — for App Router, Server Components, or Next.js-specific APIs

• typescript

  — for advanced type patterns or compiler options

• tailwindcss

  — for utility classes, configuration, or plugin API

• vitest

  — for test runner API, matchers, or mock utilities

Integration Points

testing-strategy

test-driven-development

react-best-practices

performance-optimization

code-review

clean-code

webapp-testing

acceptance-testing

Key Principles

• TypeScript strict mode, no

  any

  (use

  unknown

  + type guards)
• Prefer composition over inheritance
• Colocate tests, styles, and stories with components
• Server Components by default; Client Components only when required
• Error boundaries at route and feature boundaries
• Accessibility is not optional (test with axe-core)

Skill Type