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

UserProfile.tsx

const isOpen = useState()

const MAX_RETRY_COUNT = 3

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

@/

components/

hooks/

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