Frontend Developer Skill

Expert frontend development using Next.js 15, React 19, and TailwindCSS with a Material Design-inspired theme system.

Core Principles

1. Server Components First

Always prefer React Server Components over Client Components:

✅ Default to Server Components:

// app/projects/page.tsx
import { getProjects } from "@/models/projects";

export default async function ProjectsPage() {
  const projects = await getProjects();
  return <ProjectList projects={projects} />;
}

❌ Only use Client Components when needed:

'use client'; // Only add when you need:
// - useState, useEffect, or other React hooks
// - Event handlers (onClick, onChange, etc.)
// - Browser APIs (window, document, etc.)
// - Third-party libraries that require client-side

2. Theme System - Always Consult globals.css

CRITICAL: Always read src/app/globals.css before writing any CSS or Tailwind classes.

The project uses a Material Design-inspired theme with semantic color tokens:

• --primary, --on-primary
• --secondary, --on-secondary
• --surface, --on-surface
• --background, --on-background
• --error, --on-error

Light/dark mode: Use light-dark() CSS function for theme-aware colors.

✅ Correct - Use theme tokens:

<div className="bg-surface text-on-surface">
  <button className="bg-primary text-on-primary">Click me</button>
</div>

❌ Wrong - Hardcoded colors:

<div className="bg-white text-black dark:bg-gray-900 dark:text-white">
  <button className="bg-blue-500 text-white">Click me</button>
</div>

3. Component Organization

Break apart large components to keep files focused and maintainable:

✅ Good structure:

app/meals/
├── page.tsx              # Main page (100 lines)
├── meal-list.tsx         # List component (80 lines)
├── meal-card.tsx         # Card component (60 lines)
└── meal-filters.tsx      # Filters component (50 lines)

❌ Avoid:

app/meals/
└── page.tsx              # Everything in one file (500+ lines)

4. Server Actions for Forms

Use server actions for form submissions, not API routes:

✅ Correct:

// app/meals/new/page.tsx
import { createMeal } from "@/actions/meals";

export default function NewMealPage() {
  return (
    <form action={createMeal}>
      <input name="name" required />
      <button type="submit">Create</button>
    </form>
  );
}

For client-side validation or loading states, use useFormState or useFormStatus:

"use client"
import { useFormState } from "react-dom";
import { createMeal } from "@/actions/meals";

export default function MealForm() {
  const [state, formAction] = useFormState(createMeal, null);

  return (
    <form action={formAction}>
      {state?.error && <p className="text-error">{state.error}</p>}
      <input name="name" required />
      <button type="submit">Create</button>
    </form>
  );
}

Directory Structure

src/app/

Next.js 15 App Router pages and layouts.

Organization:

• app/layout.tsx - Root layout with theme provider
• app/page.tsx - Home page
• app/[feature]/ - Feature-based organization (meals, recipes, etc.)
• app/api/ - API routes (use sparingly, prefer server actions)
• app/globals.css - ALWAYS CONSULT FOR THEME TOKENS

src/components/

Reusable components.

Naming conventions:

• Use kebab-case for file names: meal-card.tsx
• Use PascalCase for component names: MealCard
• Co-locate related components in feature folders

Example structure:

components/
├── ui/              # Generic UI components
│   ├── button.tsx
│   ├── card.tsx
│   └── input.tsx
├── meals/           # Meal-specific components
│   ├── meal-card.tsx
│   └── meal-list.tsx
└── layout/          # Layout components
    ├── header.tsx
    └── nav.tsx

Styling Guidelines

Theme Tokens

Always use semantic color tokens from globals.css:

Background colors:

• bg-background - Page background
• bg-surface - Card/panel backgrounds
• bg-primary - Primary actions
• bg-secondary - Secondary actions
• bg-error - Error states

Text colors:

• text-on-background - Text on background
• text-on-surface - Text on surface
• text-on-primary - Text on primary
• text-on-secondary - Text on secondary
• text-on-error - Text on error

Example card component:

<div className="bg-surface text-on-surface rounded-lg shadow-md p-4">
  <h2 className="text-xl font-semibold mb-2">Card Title</h2>
  <p className="text-on-surface/80">Card content goes here</p>
  <button className="mt-4 bg-primary text-on-primary px-4 py-2 rounded">
    Action
  </button>
</div>

Responsive Design

Use Tailwind's responsive prefixes:

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
  {/* Responsive grid */}
</div>

<nav className="flex flex-col md:flex-row gap-4">
  {/* Responsive navigation */}
</nav>

Custom CSS (when needed)

If Tailwind doesn't suffice, use the theme tokens with light-dark():

.custom-component {
  background: light-dark(var(--surface-light), var(--surface-dark));
  color: light-dark(var(--on-surface-light), var(--on-surface-dark));
}

Next.js 15 Patterns

App Router Structure

Page pattern:

// app/meals/page.tsx
import { selectMeals } from "@/models/meals";

export default async function MealsPage() {
  const meals = await selectMeals([]);
  return <MealList meals={meals} />;
}

Layout pattern:

// app/meals/layout.tsx
export default function MealsLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="container mx-auto px-4 py-8">
      <h1 className="text-3xl font-bold mb-6">Meals</h1>
      {children}
    </div>
  );
}

Loading and Error States

Loading UI:

// app/meals/loading.tsx
export default function Loading() {
  return (
    <div className="flex justify-center items-center min-h-screen">
      <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary"></div>
    </div>
  );
}

Error boundary:

// app/meals/error.tsx
"use client"

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2 className="text-2xl font-bold text-error mb-4">Something went wrong!</h2>
      <button
        onClick={reset}
        className="bg-primary text-on-primary px-4 py-2 rounded"
      >
        Try again
      </button>
    </div>
  );
}

Metadata

// app/meals/page.tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'Meals - Meze',
  description: 'Browse and manage your meals',
};

React 19 Patterns

Server Components (default)

// Async server component
async function MealDetails({ id }: { id: number }) {
  const meal = await selectMealById(id);
  return <div>{meal.name}</div>;
}

Client Components (when needed)

"use client"

import { useState } from "react";

export function MealFilters() {
  const [filter, setFilter] = useState("");

  return (
    <input
      value={filter}
      onChange={(e) => setFilter(e.target.value)}
      className="border rounded px-3 py-2"
    />
  );
}

Form Actions

// Server component with form action
import { createMeal } from "@/actions/meals";

export default function NewMealForm() {
  return (
    <form action={createMeal} className="space-y-4">
      <div>
        <label className="block text-sm font-medium mb-1">Name</label>
        <input
          name="name"
          required
          className="w-full border rounded px-3 py-2"
        />
      </div>
      <button
        type="submit"
        className="bg-primary text-on-primary px-4 py-2 rounded"
      >
        Create Meal
      </button>
    </form>
  );
}

TypeScript Best Practices

Component Props

interface MealCardProps {
  meal: SelectMeal; // From Drizzle schema
  onEdit?: (id: number) => void;
  className?: string;
}

export function MealCard({ meal, onEdit, className }: MealCardProps) {
  return (
    <div className={cn("bg-surface rounded-lg p-4", className)}>
      <h3>{meal.name}</h3>
      {onEdit && (
        <button onClick={() => onEdit(meal.id)}>Edit</button>
      )}
    </div>
  );
}

Children Types

interface ContainerProps {
  children: React.ReactNode;
  className?: string;
}

export function Container({ children, className }: ContainerProps) {
  return <div className={className}>{children}</div>;
}

Common Tasks

Create a new page

1. Create app/[feature]/page.tsx
2. Fetch data using server component (if needed)
3. Create layout in app/[feature]/layout.tsx (if needed)
4. Add loading and error states
5. Update navigation/links

Create a reusable component

1. Create file in src/components/[category]/component-name.tsx
2. Define TypeScript interface for props
3. Use theme tokens for styling
4. Keep it focused (under 100 lines)
5. Export as named export

Add a form with validation

1. Create server action in src/actions/
2. Add Zod validation in the action
3. Create form component (server or client)
4. Use useFormState for client-side feedback (if needed)
5. Return success/error objects from action

Style a component

1. First: Read src/app/globals.css to understand available theme tokens
2. Use Tailwind classes with theme colors (bg-primary, text-on-surface, etc.)
3. Use responsive prefixes (md:, lg:) for breakpoints
4. For complex cases, use custom CSS with light-dark() function
5. Test in both light and dark modes

Testing

E2E Testing with Playwright

// tests/e2e/meals.spec.ts
import { test, expect } from '@/tests/e2e/fixtures';

test('can create a meal', async ({ page, authenticatedUser }) => {
  await page.goto('/meals/new');
  await page.fill('input[name="name"]', 'Test Meal');
  await page.click('button[type="submit"]');
  await expect(page).toHaveURL(/\/meals\/\d+/);
});

See tests/e2e/README.md for fixtures and patterns.

Component Testing

// tests/unit/components/meal-card.test.tsx
import { render, screen } from "@testing-library/react";
import { MealCard } from "@/components/meals/meal-card";
import { mealFactory } from "@/tests/factories";

test("renders meal name", async () => {
  const meal = await mealFactory.create();
  render(<MealCard meal={meal} />);
  expect(screen.getByText(meal.name)).toBeInTheDocument();
});

Reference Documentation

Always consult these resources when working in their areas:

• src/app/globals.css - Theme system with semantic color tokens (CRITICAL - read before any styling)
• src/app/README.md - App directory patterns, import rules, and server component guidelines
• src/components/ui/README.md - UI components wrapper layer and design system integration (CRITICAL)
• src/lib/glass-components/README.md - Glass components design system philosophy and portability
• tests/README.md - Testing architecture overview and three-tier testing approach
• tests/e2e/README.md - E2E testing patterns, fixtures, and Playwright best practices
• tests/factories/README.md - Factory pattern for generating test data with minimal parameters

Common Patterns

Data fetching pattern

// Server component
async function MealsPage() {
  const meals = await selectMeals([]);

  if (meals.length === 0) {
    return <EmptyState />;
  }

  return <MealList meals={meals} />;
}

Interactive list pattern

// app/meals/page.tsx - Server component
import { MealList } from "./meal-list";

export default async function MealsPage() {
  const meals = await selectMeals([]);
  return <MealList meals={meals} />;
}

// app/meals/meal-list.tsx - Client component
"use client"

import { useState } from "react";

export function MealList({ meals }: { meals: SelectMeal[] }) {
  const [filter, setFilter] = useState("");

  const filtered = meals.filter(m =>
    m.name.toLowerCase().includes(filter.toLowerCase())
  );

  return (
    <div>
      <input
        value={filter}
        onChange={(e) => setFilter(e.target.value)}
        placeholder="Filter meals..."
        className="border rounded px-3 py-2 mb-4 w-full"
      />
      <div className="grid gap-4">
        {filtered.map(meal => (
          <MealCard key={meal.id} meal={meal} />
        ))}
      </div>
    </div>
  );
}

Modal/Dialog pattern

"use client"

import { useState } from "react";
import { createPortal } from "react-dom";

export function Modal({
  isOpen,
  onClose,
  children
}: {
  isOpen: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  if (!isOpen) return null;

  return createPortal(
    <div className="fixed inset-0 bg-black/50 flex items-center justify-center">
      <div className="bg-surface text-on-surface rounded-lg p-6 max-w-md w-full">
        {children}
        <button
          onClick={onClose}
          className="mt-4 bg-primary text-on-primary px-4 py-2 rounded"
        >
          Close
        </button>
      </div>
    </div>,
    document.body
  );
}

Troubleshooting

Hydration errors

Symptom: "Text content does not match server-rendered HTML"

Solution: Avoid using browser-only APIs in server components

// ❌ Wrong
const isClient = typeof window !== 'undefined';

// ✅ Correct - Use client component
"use client"
export function ClientOnly() {
  const [mounted, setMounted] = useState(false);

  useEffect(() => setMounted(true), []);

  if (!mounted) return null;
  return <div>{/* browser-dependent content */}</div>;
}

Theme colors not working

Solution: Always check src/app/globals.css for available tokens. Use semantic names, not hardcoded colors.

Form not submitting

Check: Is the server action marked with "use server"? Check: Are you returning the right shape from the action? Check: Is error handling in place?