Pier_v1/.hmcmkit/knowledge/templates/pipeline/phase-6-ui.template.md

UI Implementation Specification

Phase 6 Deliverable: Screen implementation and API integration

Project: {{project_name}} Date: {{date}} Version: 1.0

---

1. Page List

Page	Route	File	Status
Home	/	app/page.tsx	⬜
Login	/login	app/login/page.tsx	⬜

---

2. Page Details

2.1 {{PageName}}

Route: {{path}} File: {{file}}

Layout:

┌─────────────────────────────────┐
│           Header                │
├─────────────────────────────────┤
│                                 │
│           Content               │
│                                 │
└─────────────────────────────────┘

Components Used:

• Header
• Card
• Button

API Integration:

API	Purpose	Hook
GET /api/users	User list	useUsers()

State Management:

• isLoading: Loading state
• error: Error state
• data: Data

---

3. Custom Hooks

3.1 useAuth

function useAuth() {
  // Authentication state management
  return { user, login, logout, isLoading }
}

3.2 use{{Resource}}

function use{{Resource}}() {
  // {{Resource}} CRUD
  return { data, isLoading, error, create, update, remove }
}

---

4. State Management Architecture

Server State: React Query / SWR
├── useQuery: Read operations
├── useMutation: Create/Update/Delete
└── Cache invalidation

Client State: useState / Zustand
├── UI state (modals, toggles, etc.)
└── Form state

Global State: Context / Zustand
├── Authentication info
└── Theme settings

---

5. API Client Architecture

5.1 3-Layer Structure

UI Components
     ↓
Service Layer (business logic)
     ↓
API Client Layer (HTTP communication)

5.2 API Client Configuration

// lib/api/client.ts
class ApiClient {
  private baseUrl: string

  async request<T>(endpoint: string, config = {}): Promise<ApiResponse<T>> {
    const headers = new Headers(config.headers)
    headers.set('Content-Type', 'application/json')

    // Auto-inject token
    const token = this.getToken()
    if (token) headers.set('Authorization', `Bearer ${token}`)

    // Execute request and handle errors
    // ...
  }
}

export const apiClient = new ApiClient()

5.3 Service Layer Pattern

// services/{{resource}}Service.ts
export const {{resource}}Service = {
  getList(filter?: Filter) {
    return apiClient.get<PaginatedResponse<Item>>('/{{resources}}', params)
  },
  getById(id: string) {
    return apiClient.get<Item>(`/{{resources}}/${id}`)
  },
  create(data: CreateInput) {
    return apiClient.post<Item>('/{{resources}}', data)
  },
  update(id: string, data: UpdateInput) {
    return apiClient.put<Item>(`/{{resources}}/${id}`, data)
  },
  delete(id: string) {
    return apiClient.delete<void>(`/{{resources}}/${id}`)
  },
}

---

6. Error Handling

6.1 Error Type Definition

// types/api.ts
interface ApiError {
  code: string
  message: string
  details?: Array<{ field: string; message: string }>
}

// Error code constants
const ERROR_CODES = {
  VALIDATION_ERROR: 'Please check your input',
  UNAUTHORIZED: 'Login required',
  FORBIDDEN: 'Permission denied',
  NOT_FOUND: 'Resource not found',
  INTERNAL_ERROR: 'Server error occurred',
} as const

6.2 Error Boundary

<ErrorBoundary fallback={<ErrorPage />}>
  <App />
</ErrorBoundary>

6.3 API Error Handling

// In custom hook
if (error) {
  const message = ERROR_CODES[error.code] || error.message
  return <Alert variant="destructive">{message}</Alert>
}

---

7. Client-Side Security

7.1 Security Checklist

• XSS prevention (escape user input)
• CSRF token included (in API requests)
• No sensitive info stored on client
• httpOnly cookies used (auth tokens)

7.2 Token Management

// Recommended: httpOnly cookies (server-side setting)
// Fallback: localStorage (aware of XSS risk)
localStorage.setItem('auth_token', token)

// Prohibited: Storing passwords, card numbers, etc.

---

8. Validation Checklist

8.1 UI Implementation

• All pages implemented
• Responsive design applied
• Design system (Phase 5) followed

8.2 API Integration

• API client 3-layer structure applied
• Service layer separated
• API response format (Phase 4) followed

8.3 State Management

• Loading state handled
• Error state handled
• User-friendly error messages per error code

8.4 Security (Phase 7 prep)

• XSS prevention applied
• No sensitive data exposed

---

9. Next Steps

Proceed to Phase 7: SEO/Security