Frontend Specialist Skill

This skill provides TheMoon project-specific frontend patterns, Latte theme guidelines, and React/TypeScript conventions for Agent 2.

Project Structure

frontend/
├── app/                    # Next.js 14 App Router pages
│   ├── (routes)/          # Route groups
│   ├── api/               # API routes
│   └── layout.tsx         # Root layout
├── components/
│   ├── ui/                # Base UI components (shadcn/ui)
│   ├── layouts/           # Layout components
│   └── [feature]/         # Feature-specific components
├── hooks/                 # Custom React hooks
├── lib/
│   ├── api.ts            # API client and types
│   └── utils.ts          # Utility functions
└── public/               # Static assets

Latte Theme Guidelines

Color Palette

TheMoon uses the Catppuccin Latte color scheme:

Typography

• Headings: font-semibold with appropriate sizing
• Body: Default text-base (16px)
• Captions: text-sm text-muted-foreground

Component Patterns

Standard Component Structure

tsx
1// components/[feature]/FeatureCard.tsx
2"use client";
3
4import { useState } from "react";
5import { cn } from "@/lib/utils";
6
7interface FeatureCardProps {
8  title: string;
9  description?: string;
10  className?: string;
11  children?: React.ReactNode;
12}
13
14export function FeatureCard({
15  title,
16  description,
17  className,
18  children,
19}: FeatureCardProps) {
20  return (
21    <div className={cn(
22      "rounded-lg border bg-card p-4 shadow-sm",
23      "hover:shadow-md transition-shadow",
24      className
25    )}>
26      <h3 className="font-semibold text-lg">{title}</h3>
27      {description && (
28        <p className="text-sm text-muted-foreground mt-1">{description}</p>
29      )}
30      {children}
31    </div>
32  );
33}

Hook Pattern

tsx
1// hooks/use-feature.ts
2"use client";
3
4import { useState, useEffect, useCallback } from "react";
5import { api } from "@/lib/api";
6
7export function useFeature(id: string) {
8  const [data, setData] = useState<FeatureData | null>(null);
9  const [loading, setLoading] = useState(true);
10  const [error, setError] = useState<Error | null>(null);
11
12  const fetchData = useCallback(async () => {
13    try {
14      setLoading(true);
15      const result = await api.getFeature(id);
16      setData(result);
17    } catch (err) {
18      setError(err instanceof Error ? err : new Error("Unknown error"));
19    } finally {
20      setLoading(false);
21    }
22  }, [id]);
23
24  useEffect(() => {
25    fetchData();
26  }, [fetchData]);
27
28  return { data, loading, error, refetch: fetchData };
29}

API Integration

API Client Pattern

tsx
1// lib/api.ts
2const API_BASE = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8000";
3
4export const api = {
5  async getBeans(params?: BeanFilterParams): Promise<Bean[]> {
6    const query = new URLSearchParams(params as Record<string, string>);
7    const res = await fetch(`${API_BASE}/api/v1/beans?${query}`);
8    if (!res.ok) throw new Error("Failed to fetch beans");
9    return res.json();
10  },
11
12  // Add more methods following this pattern
13};

Type Definitions

Keep TypeScript types in sync with backend Pydantic schemas:

tsx
1// lib/api.ts - Types section
2export interface Bean {
3  id: number;
4  name: string;
5  origin: string;
6  roast_level?: string;
7  created_at: string;
8}
9
10export interface BeanFilterParams {
11  skip?: number;
12  limit?: number;
13  origin?: string;
14}

Animation Guidelines

Preferred: CSS Transitions

tsx
1// Use Tailwind transitions for simple animations
2<div className="transition-all duration-200 hover:scale-105 hover:shadow-lg">
3  {/* content */}
4</div>

Complex Animations: Framer Motion

tsx
1import { motion } from "framer-motion";
2
3<motion.div
4  initial={{ opacity: 0, y: 20 }}
5  animate={{ opacity: 1, y: 0 }}
6  transition={{ duration: 0.3 }}
7>
8  {/* content */}
9</motion.div>

Loading States

tsx
1// Use skeleton loaders for better UX
2<div className="animate-pulse">
3  <div className="h-4 bg-muted rounded w-3/4 mb-2" />
4  <div className="h-4 bg-muted rounded w-1/2" />
5</div>

External Skill Integration

Using frontend-design Skill

For significant new UI work, invoke the external frontend-design skill:

/frontend-design "Create a coffee bean card component with roast level indicator"

This generates production-grade, aesthetically distinctive interfaces.

Build Verification

Before completing any task:

bash
1cd frontend && npm run build

Common build issues:

• TypeScript type errors → Fix types or add proper interfaces
• Missing dependencies → Check imports
• SSR issues → Add "use client" directive

Coordination with Backend

Request API Changes

When frontend needs new API functionality:

@Agent3: API endpoint /api/v1/beans needs 'roast_level' filter parameter.
Current: GET /api/v1/beans?skip=0&limit=100
Needed: GET /api/v1/beans?skip=0&limit=100&roast_level=medium

Handle API Updates

When Agent 3 notifies of API changes:

1. Update types in lib/api.ts
2. Update affected components
3. Test with new API contract
4. Run build verification

Additional Resources

Reference Files

• references/latte-theme.md - Complete color palette and design tokens
• references/component-patterns.md - Advanced component templates

Examples

• examples/feature-card.tsx - Standard card component
• examples/data-table.tsx - Table with sorting and filtering

Quick Reference