Frontend Core Skill

When to Use

• •Creating React components or pages
• •Implementing forms with validation
• •Setting up data fetching or state management
• •Working with routing (/c, /o, /t)
• •Working with files under frontend/

CRITICAL: Irreversible Action Confirmation (MANDATORY)

Redeem Flow

Customer screen shows "사용 처리" button → Trigger 2-step modal:

Modal Content:

• •Title: "되돌릴 수 없는 작업입니다"
• •Body: "매장 직원이 확인 후 눌러주세요"
• •Buttons: [취소] (easy to hit) / [확인]

TTL Enforcement:

• •If modal not confirmed within 30-60s → auto-expire
• •Show "요청이 만료되었습니다" → retry CTA

Why This Matters:

• •Prevents accidental customer-only redemption
• •Forces store-side confirmation
• •Abuse mitigation (no auto-click scripts)

Stack

Default (popular) stack:

• •React + TypeScript + Vite
• •Tailwind CSS
• •React Router
• •TanStack Query
• •Axios
• •React Hook Form + Zod

Libraries Policy

• •Use the existing stack first
• •Adding a new library requires:
  • •clear benefit
  • •small footprint
  • •at least one example usage

Architecture

User Types & Viewports

• •Customer Wallet: mobile-first
• •Owner Backoffice: desktop-first
• •Store Terminal: always-on approval screen

Component Composition Pattern

Page (route-level)
  └─ Container (data fetch + state)
       └─ View (presentational)

File Organization

• •src/components/ - Common UI elements
• •src/features/<feature>/components/ - Feature-specific UI

Code Style

Base: Airbnb JavaScript Style Guide, with these overrides:

• •Indentation: 4 spaces
• •Max line length: 120 characters
• •Semicolons: false

Naming Conventions

No Abbreviations:

// bad
const idx = 0

// good
const index = 0

Boolean Naming:

• •Use prefixes: is, has, can, should
• •Event handlers: handle* for functions, on* for props

// good
const handleOpen = () => {}
<Button onClick={handleOpen} />

Component Internal Order

1. •State declarations (useState)
2. •Memoization (useMemo, useCallback)
3. •Side effects (useEffect)
4. •Event handlers
5. •JSX Rendering

TypeScript Rules

• •Never use any (use unknown if uncertain)
• •interface for objects (Props, API responses)
• •type for unions/aliases
• •Use as const instead of enums:

const ROLES = {
  ADMIN: "ADMIN",
  USER: "USER",
} as const

type Role = (typeof ROLES)[keyof typeof ROLES]

Prettier Config

{
  "semi": false,
  "singleQuote": true,
  "tabWidth": 4,
  "trailingComma": "es5",
  "printWidth": 120,
  "plugins": ["prettier-plugin-tailwindcss"]
}

State Branching (REQUIRED)

Every page MUST handle:

• •Loading state
• •Empty state
• •Error state (with retry CTA)

Error Handling

• •Show user-friendly message
• •Provide a recovery action (retry / back)

State & Data Fetching

TanStack Query Patterns

• •useQuery for reads
• •useMutation for writes
• •Invalidate queries on mutation success

Polling (MVP REQUIRED)

Issuance approval status and terminal lists must support polling:

• •Default interval: 2-3 seconds
• •Stop when: status is final OR TTL expires

Routing & Navigation

Use React Router.

Route Grouping

• •/c/* - customer
• •/o/* - owner/backoffice
• •/t/* - store terminal

Navigation Rules

• •Keep route params explicit (e.g., storeId, stampCardId)
• •Avoid deep nesting unless it improves clarity

Forms & Validation

• •Use react-hook-form for forms
• •Use zod schemas for validation

UX Requirements

• •Display field errors near the field
• •Disable submit while loading
• •Prevent double submits

Import Rules

Use Absolute Paths

Use @/ prefix for major directories (components/, hooks/, etc.)

Import Sorting Order

1. •React core libraries
2. •Third-party libraries
3. •Global/Common components
4. •Domain-specific components
5. •Hooks, Utils, Types
6. •Assets (images, css)

Control Flow & Depth

• •Braces Required: Do not omit {} even for single-line if
• •Depth Limit: Maintain depth of 1 or less (max 2)
• •Actively use early returns

Linting & Formatting

Tools:

• •ESLint: Code quality, accessibility (a11y), import sorting
• •Prettier: Code formatting and Tailwind class sorting
• •Husky & lint-staged: Automated verification before git commit

PR Checklist

• • Loading/Empty/Error states exist
• • Keyboard navigation works
• • Mobile-first layout checked
• • No unnecessary re-renders / infinite loops
• • API errors are handled