Design System

When to Use

• •Styling KKOOKK components with Tailwind CSS v4.0
• •Implementing KKOOKK-specific layouts and interactions
• •Adding accessibility (a11y) features
• •Building mobile-optimized web UI

Core Design Principles

1. •Tactile Certainty (물리적 확신): Mimic physical stamp sensation through visual feedback
2. •Paperless Freedom (지갑의 자유): Light, mobile-first, no-install PWA experience
3. •Human Bridge (연결의 가치): Warm digital connection between owners and customers

UI Component Library

• •Base: shadcn/ui (Radix UI primitives + Tailwind)
• •Install components as needed: npx shadcn@latest add button dialog ...
• •Components copied to src/components/ui/ — customize freely
• •Do NOT install other UI libraries without approval

When to Use shadcn/ui

Tailwind CSS v4.0

Configuration

All custom colors defined in frontend/src/assets/styles/index.css using @theme

Quick reference:

• •Primary CTA: bg-kkookk-orange-500 (#FF4D00)
• •Owner: bg-kkookk-indigo, text-kkookk-steel
• •Customer: bg-kkookk-sand, text-kkookk-yellow
• •Background: bg-kkookk-paper (#FAF9F6)
• •Text: text-kkookk-navy (#1A1C1E)

shadcn/ui vs KKOOKK Colors

Why: shadcn uses CSS variables (--primary), custom components use direct color classes.

Class Organization Order

1. •Layout (flex/grid, position)
2. •Spacing (p/m/gap)
3. •Size (w/h)
4. •Typography (text-, font-)
5. •Colors (bg-, text-, border-*)
6. •Effects (shadow, rounded, opacity)
7. •States (hover:, focus:, active:, disabled:)

Conditional Classes

import { twMerge } from 'tailwind-merge';

<div className={twMerge(
    "flex items-center p-4 rounded-xl",
    isActive && "bg-kkookk-orange-500 text-white",
    isDisabled && "opacity-50 cursor-not-allowed"
)}>

Pattern Extraction

If a class combination appears 3+ times, extract it to:

• •A reusable component, OR
• •A utility in @layer utilities (see .btn-primary in index.css)

Color System

Color Usage

• •Primary CTA: bg-kkookk-orange-500 (#FF4D00)
• •Owner UI: Indigo (#2E58FF) + Steel Gray (#64748B) - professional tone
• •Customer UI: Sand (#F5F5F0) + Yellow (#FFD600) - warm, friendly
• •Error: text-kkookk-red (#DC2626)
• •Warning: text-kkookk-amber (#F59E0B)

WCAG AAA Compliance

• •Minimum 7:1 contrast ratio
• •Navy Black on Paper White: 14.8:1 ✅
• •Test under 400+ lux (outdoor)

Typography

Type Scale

Font: Pretendard Variable

Components

KKOOKK Stamp Card

<div className="p-4 rounded-2xl shadow-lg bg-white">

Buttons

Use utility classes from index.css:

• •.btn-primary - Orange CTA
• •.btn-secondary - Indigo
• •.btn-outline, .btn-ghost

Requirements:

• •Height: h-14 (56px) - prevents accidental taps
• •Radius: rounded-2xl (16px)
• •Active: active:scale-95 - tactile feedback
• •Anti-double-tap: Disable 300ms after click

const [isProcessing, setIsProcessing] = useState(false);

const handleClick = async () => {
  if (isProcessing) return;
  setIsProcessing(true);
  try {
    await action();
  } finally {
    setTimeout(() => setIsProcessing(false), 300);
  }
};

Accessibility

Minimum Requirements

Focus States

<button className="focus:outline-none focus:ring-4 focus:ring-kkookk-orange-500/50 focus:ring-offset-2">

Form Labels

<label htmlFor="store-name" className="text-sm font-medium">매장 이름</label>
<input id="store-name" aria-required="true" aria-invalid={!!errors.storeName} />
{errors.storeName && <p id="store-name-error" className="text-sm text-kkookk-red">{errors.storeName.message}</p>}

Icon Buttons

<button aria-label="닫기"><CloseIcon /></button>

Keyboard Navigation

• •Tab order must be logical
• •Escape closes modals
• •Enter/Space activates buttons

Animations

Signature: Stamp Impact

<motion.div animate={{ scale: [0.8, 1.1, 1.0] }} transition={{ duration: 0.2 }}>

Page Transitions

<motion.div initial={{ x: '100%' }} animate={{ x: 0 }} exit={{ x: '100%' }}>

Modal Slide-up

<motion.div initial={{ y: '100%' }} animate={{ y: 0 }} className="fixed inset-x-0 bottom-0 rounded-t-3xl">

Polling Pulse

<motion.div animate={{ scale: [1, 1.05, 1], opacity: [1, 0.8, 1] }} transition={{ duration: 1.5, repeat: Infinity }}>

State Matrix

Page Type Guidelines

Owner Pages (백오피스)

• •Tone: Professional, efficient
• •Colors: Indigo, Steel Gray
• •Layout: Desktop-first, 2-3 column grid
• •CTA: Top-right (+ New)

<div className="flex items-center justify-between mb-6">
  <h1 className="text-2xl font-semibold">Title</h1>
  <button className="btn-secondary">+ New</button>
</div>
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

Customer Pages (지갑)

• •Tone: Warm, encouraging
• •Colors: Orange, Sand, Yellow
• •Layout: Mobile-first, single column
• •CTA: Fixed bottom, full width

<div className="px-4 pt-8 pb-6 text-center">
  <p className="text-6xl font-extrabold text-kkookk-orange-500">12</p>
  <p className="text-base text-kkookk-steel mt-2">개 적립</p>
</div>
<div className="fixed bottom-0 inset-x-0 p-4 bg-white border-t">
  <button className="btn-primary w-full">Action</button>
</div>

Terminal Pages (단말)

• •Tone: Clear, fast decisions
• •Colors: White background, Orange accent
• •Layout: Center-aligned, large elements
• •CTA: Approval/Reject side-by-side

<div className="min-h-screen bg-white flex flex-col items-center justify-center p-6">
  <div className="flex gap-4">
    <button className="h-14 px-8 bg-kkookk-steel text-white">거절</button>
    <button className="h-14 px-8 bg-kkookk-orange-500 text-white">승인</button>
  </div>
</div>

Edge Cases

Empty State

<div className="flex flex-col items-center gap-4 py-8 text-center">
  <EmptyIcon className="w-16 h-16 text-slate-400" />
  <p className="text-base">아직 스탬프가 없어요</p>
  <button className="btn-primary">첫 도장 모으러 가기</button>
</div>

Error State

<div className="flex flex-col items-center gap-4 py-8">
  <ErrorIcon className="w-16 h-16 text-kkookk-red" />
  <p className="text-base">네트워크 연결을 확인해주세요</p>
  <button className="btn-primary" onClick={retry}>다시 시도</button>
</div>

Mobile Optimization

• •Outdoor visibility: High contrast (Navy on Paper = 14.8:1)
• •Touch targets: Minimum 56px (h-14)
• •Spacing: Minimum 8px between targets (gap-2)
• •Safe areas: px-4 horizontal margin
• •Mobile-first: Design for 375px, enhance for larger

Instructions for Claude

1. •Always check index.css for colors and utilities
2. •Apply class organization order for every component
3. •Use twMerge for conditional classes
4. •Extract patterns after 3+ repetitions
5. •Every CTA needs anti-double-tap (300ms disable)
6. •All interactive elements need focus rings
7. •Mobile-first: 375px base, enhance with md:, lg:
8. •If violates accessibility, suggest compliant alternative
9. •When creating pages: Match page type (Owner/Customer/Terminal) guidelines
10. •When adding animations: Use Framer Motion for complex, CSS classes for simple