Frontend Engineer Skill

Purpose: Expert frontend engineering with simplified pragmatic architecture, React 19, TanStack ecosystem, and Zustand state management. Provides implementation examples for building testable, maintainable, scalable frontend applications.

When to Use:

Implementing frontend features and components
Setting up project structure
Creating pages and state management
Designing gateway injection patterns
Setting up HTTP communication and routing
Organizing feature modules
Performance optimization and code splitting

NOTE: For UI component design, Tailwind styling, shadcn/ui setup, responsive layouts, and accessibility implementation, defer to the ui-designer skill. This skill focuses on architecture, state management, and business logic orchestration.

Documentation Lookup (MANDATORY)

ALWAYS use MCP servers for up-to-date documentation:

Context7 MCP: Use for comprehensive library documentation, API reference, import statements, and version-specific patterns
- When user asks about TanStack Router, Query, Form, Table APIs
- For React 19 features and patterns
- For Vite configuration and build setup
- For Zustand API and patterns
- To verify correct import paths, hooks usage, and API patterns
Perplexity MCP: Use for architectural research, design patterns, and best practices
- When researching pragmatic frontend architectures
- For state management strategies and trade-offs
- For performance optimization techniques
- For folder structure and code organization patterns
- For troubleshooting complex architectural issues

Examples of when to use MCP:

"How to setup TanStack Router file-based routing?" → Use Context7 MCP for TanStack Router docs
"What are React 19 use() hook patterns?" → Use Context7 MCP for React docs
"How to use Zustand with TypeScript?" → Use Context7 MCP for Zustand docs
"Best practices for feature-based architecture in React?" → Use Perplexity MCP for research
"How to configure Vite with React 19?" → Use Context7 MCP for Vite docs

Tech Stack

For complete frontend tech stack details, see "Tech Stack > Frontend" section in CLAUDE.md

Quick Architecture Reference:

This skill focuses on:

Feature-based architecture (NOT Clean Architecture layers)
Gateway Pattern (Interface + HTTP + Fake)
Context API injection for testability
Zustand for global client state
TanStack Query for server state

Testing:

Unit: Vitest + React Testing Library
E2E: Playwright

→ See project-standards skill for complete tech stack → See ui-designer skill for UI/UX specific technologies → See docs/plans/2025-10-24-simplified-frontend-architecture-design.md for architecture details

Architecture Overview

Frontend follows a simplified, pragmatic, feature-based architecture.

Core Principles:

Feature-based organization - Code grouped by business functionality
Pages as use cases - Pages orchestrate business logic
Externalized state - Zustand stores are framework-agnostic, 100% testable
Gateway injection - Gateways injected via Context API for isolated testing
YAGNI rigorously - No unnecessary layers or abstractions

Design Philosophy: Simplicity and pragmatism over architectural purity. Remove Clean Architecture complexity (domain/application/infrastructure layers) in favor of direct, maintainable code.

Recommended Structure

apps/web/src/
├── app/                              # Application setup
│   ├── config/
│   │   ├── env.ts                   # Environment variables
│   │   └── index.ts
│   ├── providers/
│   │   ├── gateway-provider.tsx     # Gateway injection (Context API)
│   │   ├── query-provider.tsx       # TanStack Query setup
│   │   ├── theme-provider.tsx       # Theme provider (shadcn/ui)
│   │   └── index.ts
│   ├── router.tsx                   # TanStack Router configuration
│   └── main.tsx                     # Application entry point
│
├── features/                         # Feature modules (self-contained)
│   ├── auth/
│   │   ├── components/              # Pure UI components
│   │   │   ├── login-form.tsx
│   │   │   └── index.ts
│   │   ├── pages/                   # Use cases - orchestrate logic
│   │   │   ├── login-page.tsx
│   │   │   └── index.ts
│   │   ├── stores/                  # Zustand stores - testable entities
│   │   │   ├── auth-store.ts
│   │   │   └── index.ts
│   │   ├── gateways/                # External resource abstractions
│   │   │   ├── auth-gateway.ts      # Interface + HTTP implementation
│   │   │   ├── auth-gateway.fake.ts # Fake for unit tests
│   │   │   └── index.ts
│   │   ├── hooks/                   # Custom hooks (optional)
│   │   │   └── index.ts
│   │   ├── types/                   # TypeScript types
│   │   │   ├── user.ts
│   │   │   └── index.ts
│   │   └── index.ts                 # Barrel file - public API
│   │
│   ├── dashboard/
│   └── profile/
│
├── shared/                           # Shared code across features
│   ├── services/                    # Global services
│   │   ├── http-api.ts             # HTTP client base (Axios wrapper)
│   │   ├── storage.ts              # LocalStorage/Cookie abstraction
│   │   └── index.ts
│   ├── components/
│   │   ├── ui/                     # shadcn/ui components
│   │   └── layout/                 # Shared layouts
│   ├── hooks/                      # Global utility hooks
│   ├── lib/                        # Utilities and helpers
│   │   ├── validators.ts           # Zod schemas (common)
│   │   ├── formatters.ts
│   │   └── index.ts
│   └── types/                      # Global types
│
├── routes/                          # TanStack Router routes
│   ├── __root.tsx
│   ├── index.tsx
│   └── auth/
│       └── login.tsx
│
└── index.css

Benefits:

✅ Feature isolation - delete folder, remove feature
✅ No unnecessary layers - direct, maintainable code
✅ Testable business logic - Zustand stores are pure JS/TS
✅ Isolated page testing - inject fake gateways
✅ Clear separation - pages (orchestration), components (UI), stores (state)

Layer Responsibilities (MANDATORY)

1. Shared Services Layer

Purpose: Reusable infrastructure used across features.

Example - HTTP Client:

// shared/services/http-api.ts
import axios, { type AxiosInstance, type AxiosRequestConfig } from "axios";

export class HttpApi {
  private client: AxiosInstance;

  constructor(baseURL: string) {
    this.client = axios.create({
      baseURL,
      timeout: 10000,
      headers: { "Content-Type": "application/json" },
    });

    // Auto-inject auth token
    this.client.interceptors.request.use((config) => {
      const token = localStorage.getItem("auth_token");
      if (token) config.headers.Authorization = `Bearer ${token}`;
      return config;
    });

    // Handle 401 globally
    this.client.interceptors.response.use(
      (response) => response,
      (error) => {
        if (error.response?.status === 401) {
          localStorage.removeItem("auth_token");
          window.location.href = "/auth/login";
        }
        return Promise.reject(error);
      }
    );
  }

  async get<T>(url: string, config?: AxiosRequestConfig) {
    const response = await this.client.get<T>(url, config);
    return response.data;
  }

  async post<T>(url: string, data?: unknown, config?: AxiosRequestConfig) {
    const response = await this.client.post<T>(url, data, config);
    return response.data;
  }

  async put<T>(url: string, data?: unknown, config?: AxiosRequestConfig) {
    const response = await this.client.put<T>(url, data, config);
    return response.data;
  }

  async delete<T>(url: string, config?: AxiosRequestConfig) {
    const response = await this.client.delete<T>(url, config);
    return response.data;
  }
}

// Singleton instance
export const httpApi = new HttpApi(import.meta.env.VITE_API_URL);

2. Gateway Layer

Purpose: Abstract external resource access. Enable testing with fakes.

Example - Auth Gateway:

// features/auth/gateways/auth-gateway.ts
import { httpApi } from "@/shared/services/http-api";
import type { User } from "../types/user";

export interface LoginRequest {
  email: string;
  password: string;
}

export interface LoginResponse {
  user: User;
  token: string;
}

// Gateway interface (contract)
export interface AuthGateway {
  login(request: LoginRequest): Promise<LoginResponse>;
  logout(): Promise<void>;
  getCurrentUser(): Promise<User>;
}

// Real implementation (HTTP)
export class AuthHttpGateway implements AuthGateway {
  async login(request: LoginRequest): Promise<LoginResponse> {
    return httpApi.post<LoginResponse>("/auth/login", request);
  }

  async logout(): Promise<void> {
    await httpApi.post("/auth/logout");
  }

  async getCurrentUser(): Promise<User> {
    return httpApi.get<User>("/auth/me");
  }
}

// Fake implementation for unit tests
export class AuthFakeGateway implements AuthGateway {
  private shouldFail = false;

  setShouldFail(value: boolean) {
    this.shouldFail = value;
  }

  async login(request: LoginRequest): Promise<LoginResponse> {
    await new Promise((resolve) => setTimeout(resolve, 100));

    if (this.shouldFail) {
      throw new Error("Invalid credentials");
    }

    if (
      request.email === "test@example.com" &&
      request.password === "password123"
    ) {
      return {
        user: {
          id: "1",
          name: "Test User",
          email: "test@example.com",
          role: "user",
        },
        token: "fake-token-123",
      };
    }

    throw new Error("Invalid credentials");
  }

  async logout(): Promise<void> {
    await new Promise((resolve) => setTimeout(resolve, 50));
  }

  async getCurrentUser(): Promise<User> {
    if (this.shouldFail) throw new Error("Unauthorized");
    return {
      id: "1",
      name: "Test User",
      email: "test@example.com",
      role: "user",
    };
  }
}

3. Gateway Injection (Context API)

Purpose: Provide gateways to components. Allow override in tests.

Example:

// app/providers/gateway-provider.tsx
import { createContext, useContext, type ReactNode } from "react";
import {
  AuthGateway,
  AuthHttpGateway,
} from "@/features/auth/gateways/auth-gateway";

interface Gateways {
  authGateway: AuthGateway;
  // Add more gateways as needed
}

const GatewayContext = createContext<Gateways | null>(null);

interface GatewayProviderProps {
  children: ReactNode;
  gateways?: Partial<Gateways>; // Allow override for tests
}

export function GatewayProvider({ children, gateways }: GatewayProviderProps) {
  const defaultGateways: Gateways = {
    authGateway: new AuthHttpGateway(),
  };

  const value = { ...defaultGateways, ...gateways };

  return (
    <GatewayContext.Provider value={value}>{children}</GatewayContext.Provider>
  );
}

export function useGateways() {
  const context = useContext(GatewayContext);
  if (!context) {
    throw new Error("useGateways must be used within GatewayProvider");
  }
  return context;
}

4. Store Layer (Zustand)

Purpose: Testable business logic, framework-agnostic state management.

Example:

// features/auth/stores/auth-store.ts
import { create } from "zustand";
import type { User } from "../types/user";

interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
  error: string | null;

  setUser: (user: User | null) => void;
  setLoading: (loading: boolean) => void;
  setError: (error: string | null) => void;
  reset: () => void;
}

export const useAuthStore = create<AuthState>((set) => ({
  user: null,
  isAuthenticated: false,
  isLoading: false,
  error: null,

  setUser: (user) => set({ user, isAuthenticated: user !== null }),
  setLoading: (isLoading) => set({ isLoading }),
  setError: (error) => set({ error }),
  reset: () =>
    set({ user: null, isAuthenticated: false, isLoading: false, error: null }),
}));

Why Zustand:

✅ Minimal boilerplate
✅ Excellent TypeScript support
✅ Framework-agnostic (100% testable without React)
✅ Large community and ecosystem
✅ Superior DX compared to alternatives

5. Page Layer (Use Cases)

Purpose: Orchestrate business logic by coordinating gateways, stores, and UI components.

Example:

// features/auth/pages/login-page.tsx
import { useState } from "react";
import { useNavigate } from "@tanstack/react-router";
import { useGateways } from "@/app/providers/gateway-provider";
import { useAuthStore } from "../stores/auth-store";
import { LoginForm } from "../components/login-form";

export function LoginPage() {
  const navigate = useNavigate();
  const { authGateway } = useGateways(); // Injected gateway
  const { setUser, setLoading, setError, isLoading, error } = useAuthStore();

  const [formError, setFormError] = useState<string | null>(null);

  const handleLogin = async (email: string, password: string) => {
    setLoading(true);
    setError(null);
    setFormError(null);

    try {
      const { user, token } = await authGateway.login({ email, password });

      localStorage.setItem("auth_token", token);
      setUser(user);

      navigate({ to: "/dashboard" });
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : "Login failed";
      setError(errorMessage);
      setFormError(errorMessage);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="flex min-h-screen items-center justify-center">
      <LoginForm
        onSubmit={handleLogin}
        isLoading={isLoading}
        error={formError}
      />
    </div>
  );
}

6. Component Layer

Purpose: Pure UI components that receive props and emit events.

Example:

// features/auth/components/login-form.tsx
import { useState } from "react";
import { Button } from "@/shared/components/ui/button";
import { Input } from "@/shared/components/ui/input";

interface LoginFormProps {
  onSubmit: (email: string, password: string) => void;
  isLoading?: boolean;
  error?: string | null;
}

export function LoginForm({
  onSubmit,
  isLoading = false,
  error,
}: LoginFormProps) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    onSubmit(email, password);
  };

  return (
    <form onSubmit={handleSubmit} className="w-full max-w-md space-y-4">
      <div>
        <Input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          disabled={isLoading}
          aria-label="Email"
        />
      </div>

      <div>
        <Input
          type="password"
          placeholder="Password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          disabled={isLoading}
          aria-label="Password"
        />
      </div>

      {error && <p className="text-sm text-red-600">{error}</p>}

      <Button type="submit" disabled={isLoading} className="w-full">
        {isLoading ? "Loading..." : "Login"}
      </Button>
    </form>
  );
}

State Management Strategy (MANDATORY)

Use the RIGHT tool for each state type:

1. Global Client State → Zustand

For application-wide client state (auth, theme, preferences):

// shared/stores/theme-store.ts
import { create } from "zustand";

export type Theme = "light" | "dark" | "system";

interface ThemeState {
  theme: Theme;
  setTheme: (theme: Theme) => void;
}

export const useThemeStore = create<ThemeState>((set) => ({
  theme: "system",
  setTheme: (theme) => set({ theme }),
}));

2. Server State → TanStack Query

For data from backend APIs with caching, revalidation, and synchronization:

// features/users/hooks/use-users-query.ts
import { useQuery } from "@tanstack/react-query";
import { useGateways } from "@/app/providers/gateway-provider";

export function useUsersQuery() {
  const { userGateway } = useGateways();

  return useQuery({
    queryKey: ["users"],
    queryFn: () => userGateway.getUsers(),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

3. Form State → TanStack Form

For form management with validation:

import { useForm } from "@tanstack/react-form";
import { zodValidator } from "@tanstack/zod-form-adapter";
import { z } from "zod";

const userSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
});

export function UserForm() {
  const form = useForm({
    defaultValues: { name: "", email: "" },
    validatorAdapter: zodValidator(),
    validators: { onChange: userSchema },
    onSubmit: async ({ value }) => console.log(value),
  });

  // ... render form
}

4. URL State → TanStack Router

For URL parameters and search params:

// routes/users/$userId.tsx
import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";

const userSearchSchema = z.object({
  tab: z.enum(["profile", "settings"]).optional(),
});

export const Route = createFileRoute("/users/$userId")({
  validateSearch: userSearchSchema,
  component: UserDetail,
});

function UserDetail() {
  const { userId } = Route.useParams();
  const { tab = "profile" } = Route.useSearch();

  return (
    <div>
      User {userId} - Tab: {tab}
    </div>
  );
}

5. Local Component State → useState/useReducer

For component-specific state:

export function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

Testing Strategy (MANDATORY)

Test Pyramid

        ┌─────────────┐
       ╱   E2E Tests   ╲       Few - Critical flows
      ╱   (Playwright)  ╲
     ╱─────────────────────╲
    ╱  Integration Tests   ╲  Some - Pages with fakes
   ╱   (Pages + Stores)     ╲
  ╱─────────────────────────╲
 ╱       Unit Tests          ╲ Many - Stores, utils
╱   (Stores, Utils, Comps)   ╲
─────────────────────────────

Store Tests (Unit - High Priority)

Zustand stores are 100% testable without React:

// features/auth/stores/auth-store.test.ts
import { describe, it, expect, beforeEach } from "bun:test";
import { useAuthStore } from "./auth-store";

describe("AuthStore", () => {
  beforeEach(() => {
    useAuthStore.getState().reset();
  });

  it("should start with empty state", () => {
    const state = useAuthStore.getState();
    expect(state.user).toBeNull();
    expect(state.isAuthenticated).toBe(false);
  });

  it("should update user and isAuthenticated when setting user", () => {
    const user = {
      id: "1",
      name: "Test",
      email: "test@example.com",
      role: "user",
    };

    useAuthStore.getState().setUser(user);

    expect(useAuthStore.getState().user).toEqual(user);
    expect(useAuthStore.getState().isAuthenticated).toBe(true);
  });
});

Page Tests (Integration with Fake Gateways)

Test orchestration logic with injected fakes:

// features/auth/pages/login-page.test.tsx
import { describe, it, expect, beforeEach } from "bun:test";
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { GatewayProvider } from "@/app/providers/gateway-provider";
import { AuthFakeGateway } from "../gateways/auth-gateway";
import { LoginPage } from "./login-page";
import { useAuthStore } from "../stores/auth-store";

describe("LoginPage", () => {
  let fakeAuthGateway: AuthFakeGateway;

  beforeEach(() => {
    fakeAuthGateway = new AuthFakeGateway();
    useAuthStore.getState().reset();
  });

  it("should login successfully and update store", async () => {
    const user = userEvent.setup();

    render(
      <GatewayProvider gateways={{ authGateway: fakeAuthGateway }}>
        <LoginPage />
      </GatewayProvider>
    );

    await user.type(screen.getByLabelText(/email/i), "test@example.com");
    await user.type(screen.getByLabelText(/password/i), "password123");
    await user.click(screen.getByRole("button", { name: /login/i }));

    await waitFor(() => {
      expect(useAuthStore.getState().isAuthenticated).toBe(true);
    });
  });

  it("should show error when login fails", async () => {
    const user = userEvent.setup();
    fakeAuthGateway.setShouldFail(true);

    render(
      <GatewayProvider gateways={{ authGateway: fakeAuthGateway }}>
        <LoginPage />
      </GatewayProvider>
    );

    await user.type(screen.getByLabelText(/email/i), "wrong@example.com");
    await user.type(screen.getByLabelText(/password/i), "wrong");
    await user.click(screen.getByRole("button", { name: /login/i }));

    await waitFor(() => {
      expect(screen.getByText(/invalid credentials/i)).toBeInTheDocument();
    });
  });
});

Component Tests (Unit - Pure UI)

// features/auth/components/login-form.test.tsx
import { describe, it, expect, mock } from "bun:test";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { LoginForm } from "./login-form";

describe("LoginForm", () => {
  it("should render email and password fields", () => {
    render(<LoginForm onSubmit={mock()} />);

    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
  });

  it("should call onSubmit with correct values", async () => {
    const user = userEvent.setup();
    const onSubmit = mock();

    render(<LoginForm onSubmit={onSubmit} />);

    await user.type(screen.getByLabelText(/email/i), "test@example.com");
    await user.type(screen.getByLabelText(/password/i), "password123");
    await user.click(screen.getByRole("button", { name: /login/i }));

    expect(onSubmit).toHaveBeenCalledWith("test@example.com", "password123");
  });
});

E2E Tests (Playwright - Critical Flows)

// e2e/auth/login.spec.ts
import { test, expect } from "@playwright/test";

test.describe("Login Flow", () => {
  test("should login and redirect to dashboard", async ({ page }) => {
    await page.goto("/auth/login");

    await page.fill('input[name="email"]', "test@example.com");
    await page.fill('input[name="password"]', "password123");
    await page.click('button:has-text("Login")');

    await expect(page).toHaveURL("/dashboard");
    await expect(page.locator("text=Welcome, Test User")).toBeVisible();
  });
});

Naming Conventions (MANDATORY)

Files and Folders

Files: kebab-case with suffixes
Folders: kebab-case

features/auth/
├── components/
│   ├── login-form.tsx              # Component: kebab-case
│   └── index.ts
├── pages/
│   ├── login-page.tsx              # Suffix: -page.tsx
│   └── index.ts
├── stores/
│   ├── auth-store.ts               # Suffix: -store.ts
│   └── index.ts
├── gateways/
│   ├── auth-gateway.ts             # Suffix: -gateway.ts
│   ├── auth-gateway.fake.ts        # Suffix: -gateway.fake.ts
│   └── index.ts

Code Elements

Components:

// ✅ Good
export function LoginForm({ onSubmit }: LoginFormProps) {}

// ❌ Avoid
export const loginForm = () => {}; // No arrow function exports
export function Form() {} // Too generic

Pages:

// ✅ Good - "Page" suffix
export function LoginPage() {}

// ❌ Avoid
export function Login() {} // Confuses with component

Stores:

// ✅ Good - "use" + name + "Store"
export const useAuthStore = create<AuthState>(...);

// ❌ Avoid
export const authStore = create(...); // Missing "use" prefix

Gateways:

// ✅ Good - No "I" prefix
export interface AuthGateway {}
export class AuthHttpGateway implements AuthGateway {}
export class AuthFakeGateway implements AuthGateway {}

// ❌ Avoid
export interface IAuthGateway {} // No "I" prefix

TanStack Router Patterns (MANDATORY)

File-Based Routing

// routes/__root.tsx
import { createRootRoute, Outlet } from "@tanstack/react-router";

export const Route = createRootRoute({
  component: () => (
    <div>
      <nav>Navigation</nav>
      <Outlet />
    </div>
  ),
});

// routes/index.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/")({
  component: HomePage,
});

function HomePage() {
  return <h1>Home</h1>;
}

Type-Safe Navigation

import { Link, useNavigate } from "@tanstack/react-router";

export function Navigation() {
  const navigate = useNavigate();

  return (
    <div>
      <Link to="/users/$userId" params={{ userId: "123" }}>
        View User
      </Link>

      <button
        onClick={() => {
          navigate({ to: "/users/$userId", params: { userId: "456" } });
        }}
      >
        Go to User
      </button>
    </div>
  );
}

Component Organization Principles (MANDATORY)

1. Keep Components Small (< 150 lines)

// ✅ Good - Extract into smaller components
export function UserDashboard() {
  return (
    <div>
      <UserHeader />
      <UserStats />
      <UserActivity />
    </div>
  );
}

2. Extract Logic into Hooks (< 20 lines in component)

// ✅ Good
export function UserList() {
  const { users, loading, error } = useUsers();

  if (loading) return <Loading />;
  if (error) return <Error />;

  return <div>{/* Render users */}</div>;
}

3. One Component Per File

// ✅ Good - Separate files
// user-card.tsx
export function UserCard() {}

// user-avatar.tsx
export function UserAvatar() {}

Critical Rules

NEVER:

Use Clean Architecture layers (domain/application/infrastructure)
Import stores in components (pass data via props)
Call HTTP directly from components (use gateways)
Use any type (use unknown with type guards)
Skip TypeScript types
Use npm, pnpm, yarn (use Bun)
Create components > 150 lines
Keep logic > 20 lines in components

ALWAYS:

Organize by features (feature-based structure)
Pages orchestrate logic (use gateways + stores)
Externalize state to Zustand stores
Inject gateways via Context API
Write tests for stores (unit) and pages (integration with fakes)
Use functional components with TypeScript
One component per file
Extract logic into custom hooks
Use Bun for all package management
Run bun run craft after creating/moving files

Deliverables

When helping users, provide:

Feature Folder Structure: Organized with pages/, components/, stores/, gateways/
Gateway Definitions: Interface + HTTP implementation + Fake implementation
Gateway Provider: Context API setup for dependency injection
Zustand Stores: Framework-agnostic state management with actions
Pages: Orchestration logic using gateways and stores
Components: Pure UI components with props
Router Configuration: TanStack Router setup with type safety
Test Examples: Store tests, page tests with fakes, component tests, E2E
Configuration Files: Vite, TypeScript, TanStack configurations

Summary

Frontend architecture focuses on:

Simplicity: No unnecessary layers, direct code, pragmatic patterns
Testability: Zustand stores (pure), pages with fake gateways, isolated components
Maintainability: Feature-based structure, clear responsibilities, consistent patterns
Type Safety: Strong typing, Zod validation, TanStack Router
Performance: Code splitting, lazy loading, optimistic updates
User Experience: Error handling, loading states, toast notifications

Remember: Good architecture makes change easy. Build systems that are simple, testable, and maintainable. Avoid over-engineering. Focus on delivering value.

Reference:

Architecture design: docs/plans/2025-10-24-simplified-frontend-architecture-design.md
Project standards: project-standards skill
UI/UX: ui-designer skill

frontend-engineer

Frontend Engineer Skill

Documentation Lookup (MANDATORY)

Tech Stack

Testing:

Architecture Overview

Recommended Structure

Layer Responsibilities (MANDATORY)

1. Shared Services Layer

2. Gateway Layer

3. Gateway Injection (Context API)

4. Store Layer (Zustand)

5. Page Layer (Use Cases)

6. Component Layer

State Management Strategy (MANDATORY)

1. Global Client State → Zustand

2. Server State → TanStack Query

3. Form State → TanStack Form

4. URL State → TanStack Router

5. Local Component State → useState/useReducer

Testing Strategy (MANDATORY)

Test Pyramid

Store Tests (Unit - High Priority)

Page Tests (Integration with Fake Gateways)

Component Tests (Unit - Pure UI)

E2E Tests (Playwright - Critical Flows)

Naming Conventions (MANDATORY)

Files and Folders

Code Elements

TanStack Router Patterns (MANDATORY)

File-Based Routing

Type-Safe Navigation

Component Organization Principles (MANDATORY)

1. Keep Components Small (< 150 lines)

2. Extract Logic into Hooks (< 20 lines in component)

3. One Component Per File

Critical Rules

Deliverables

Summary

Similar Skills