YumYum 디자인 시스템 — Stratis UI Icons 토큰 v3

냠냠픽업 디자인 시스템 Stratis UI Icons 가이드 작성일: 2026-05-13 최종 갱신: 2026-05-18 — §3 아이콘 색 토큰 5종을 warm v2 → cool gray v3로 마이그레이션 버전: v3.0 (cool gray v3 시리즈)

---

1. 디자인 원칙

1.1 핵심 컨셉

• 일관된 outline 스타일 — 시각적 통일감
• 명확한 의미 전달 — 의미가 헷갈리는 아이콘 회피
• 활성 시 filled로 강조 — 시각적 위계 명확
• 사이즈는 4px Spacing 그리드와 일치

1.2 사용 라이브러리

Stratis UI Icons (1000개)

• Figma Community 무료 제공
• 일관된 outline 스타일 + filled 버전 포함
• URL: Stratis UI Icons

---

2. Sizes — 4단계

4의 배수로 구성. 컨텍스트에 따라 선택.

Token	Size	용도
icon-xs	12px	Badge/Tag 안 인라인 아이콘 (clock, map-pin)
icon-sm	16px	Small Button, Input 옆, Toast 안
icon-md ⭐	20px	기본값. List Item leading, Medium Button, 대부분 UI
icon-lg	24px	Header 액션, Tab Bar, Modal 닫기
icon-xl	32px+	Empty state, Illustration, Hero

---

3. Colors — 5단계

컬러 시스템과 동일한 토큰 사용.

Token	Color	용도
Primary	neutral-800 #333333	기본 (Header, Button, List leading)
Secondary	neutral-500 #999999	보조 (caption 옆, Input leading)
Disabled	neutral-400 #B8B8B8	비활성 (Tab Bar inactive)
Brand	yellow-500 #FFDE36	강조 (별점, Toast 액션) — 아껴 사용
Inverse	neutral-50 #FAFAFA	어두운 배경 위 (Toast, 강한 알림)

---

4. Outline vs Filled

기본은 Outline. Filled는 활성 상태나 강조 시.

4.1 Outline (기본 95%)

• 비활성 상태
• 일반 UI
• 가벼운 인상
• 예: home, heart, star, bell

4.2 Filled (활성 5%)

• 활성 상태 (Tab Bar 활성 탭)
• 좋아요 후 (heart-filled)
• 별점 (star-filled, yellow-500)
• 알림 받음 후

---

5. 컴포넌트별 아이콘 매핑

컴포넌트	Size	Color	Style
Header 액션	24px	Primary	Outline
Tab Bar (active)	22-24px	Primary	Filled
Tab Bar (inactive)	22-24px	Disabled	Outline
Button (M) leading	16-18px	라벨 색과 동일	Outline
Button (L) leading	18-20px	라벨 색과 동일	Outline
List Item leading	20px	Secondary	Outline
Input leading	18px	Secondary	Outline
Badge inline	12-14px	텍스트 색과 동일	Outline
Toast leading	18px	Inverse	Outline
Modal 닫기	22-24px	Secondary	Outline
평점 (star)	13-14px	Brand	Filled (star-filled)
Quantity stepper	18px	Primary	Outline
Chevron 이동	18-20px	Disabled	Outline

---

6. 디자인 → 개발 워크플로

6.1 디자인 단계 (Figma)

1. Stratis UI Icons 라이브러리 사용
2. Figma Variables로 아이콘 색상 토큰 연결 (icon-primary, icon-secondary 등)
3. 컴포넌트에 적용 (Auto Layout)

6.2 개발 단계 (SVG Export)

프로세스:

1. 디자이너가 사용된 아이콘만 Figma에서 SVG로 export
2. 개발자 repo의 /icons 폴더에 추가
3. 의미 있는 파일명으로 통일 (home.svg, heart-filled.svg 등)
4. React/Vue 등에서 컴포넌트로 변환 (SVGR 등 도구 활용)

파일 명명 규칙:

home.svg          ← outline 기본
home-filled.svg   ← filled 버전
chevron-left.svg
shopping-cart.svg
star-filled.svg

최적화:

• SVG는 currentColor 사용해서 CSS로 색 컨트롤
• viewBox만 남기고 width/height 제거 → 사이즈는 CSS로
• SVGO로 최적화 (불필요한 메타데이터 제거)

6.3 React 컴포넌트 예시

// Icon.tsx
import HomeIcon from '/icons/home.svg';
import HeartFilledIcon from '/icons/heart-filled.svg';

<Icon name="home" size={20} color="primary" />
// → <HomeIcon style={{ width: 20, height: 20, color: 'var(--color-neutral-800)' }} />

6.4 통합 컴포넌트 패턴 ⭐ (2026-05-18 표준화)

의미 카테고리가 같은 아이콘 묶음은 kind prop으로 통합 컴포넌트로.

예: 위치 마커 4종 (home/work/school/pin) — 사용 맥락이 같으므로 <Marker kind="home" /> 하나로 통합. 파일/import 부담 감소 + 색은 CSS로 자유롭게.

// /components/icons/Marker.tsx
export type MarkerKind = 'home' | 'work' | 'school' | 'pin'

type Props = { kind: MarkerKind; className?: string; size?: number }

export default function Marker({ kind, className, size = 24 }: Props) {
  return (
    <svg width={size} height={size} viewBox="0 0 24 24"
         fill="none" className={className} aria-hidden="true">
      {kind === 'home' && (<>{/* home paths */}</>)}
      {kind === 'work' && (<>{/* work paths */}</>)}
      {kind === 'pin'  && (<>{/* pin paths */}</>)}
      {/* ... */}
    </svg>
  )
}

핵심 spec (모든 아이콘 통일):

• viewBox="0 0 24 24"
• stroke="currentColor" ← 색은 CSS class로
• stroke-width="1.5" (Stratis UI 표준)
• stroke-linecap="round", stroke-linejoin="round"
• fill="none" (outline 기본)
• aria-hidden="true" (decorative)

색 제어 (CSS 클래스로):

<Marker kind="home" className="text-orange-main" />   // 활성/강조
<Marker kind="work" className="text-neutral-800" />   // 일반
<Marker kind="pin"  className="text-orange-main" />   // 액션 CTA

6.5 의미별 색 매핑 ⭐ (2026-05-18 표준화)

같은 아이콘이라도 의미에 따라 색을 바꿔서 사용. SVG에 색 박지 말고 컨테이너 CSS로 제어.

의미	Token	사용 사례
활성 / 현재 선택	text-orange-main (#FF8500)	현재 설정된 주소, 활성 탭 강조
CTA 액션	text-orange-main (#FF8500)	"주소 추가하기", "더 보기" 같은 텍스트 액션
일반 / 보통	text-neutral-800 (#333)	저장된 주소 마커, 카드 안 아이콘
보조 / 비활성	text-neutral-500 (#999)	비활성 탭, hint 아이콘
체크 / 성공 표시	text-orange-main (#FF8500)	선택 완료, 확인

Why: SVG 파일 안에 색을 박으면 한 색당 파일 1개. 4가지 색이 필요하면 4벌 export — 유지비용 ↑. currentColor 패턴으로 통일하면 파일 1개 + 색은 CSS class로 자유. brand 색 변경 시에도 토큰만 갱신.

---

7. YumYum 핵심 아이콘 (30개)

자주 등장하는 아이콘. 디자인 시 일관성 유지를 위해 정해두면 좋음.

7.1 Navigation (6)

• chevron-left (뒤로가기)
• chevron-right (이동)
• chevron-down (펼치기)
• x (닫기)
• arrow-left (이전)
• arrow-right (다음)

7.2 Tab Bar / Main (6)

• home (홈)
• file-text (주문내역)
• heart (즐겨찾기)
• mood-smile (마이냠냠)
• search (검색)
• bell (알림)

7.3 Action (6)

• plus (추가)
• minus (감소)
• share (공유)
• dots-vertical (더보기)
• filter (필터)
• settings (설정)

7.4 Status / Info (6)

• circle-check (성공)
• circle-x (에러)
• alert-triangle (주의)
• info-circle (정보)
• star-filled (평점) — Brand color
• flame (HOT)

7.5 Food / Domain (6)

• shopping-cart (장바구니)
• shopping-bag (픽업백)
• clock (시간)
• map-pin (위치)
• phone (전화)
• credit-card (결제)

---

8. CSS Variables 구현 예시

:root {
  /* Icon Size */
  --icon-xs: 12px;
  --icon-sm: 16px;
  --icon-md: 20px;
  --icon-lg: 24px;
  --icon-xl: 32px;

  /* Icon Color */
  --icon-color-primary: var(--color-neutral-800);
  --icon-color-secondary: var(--color-neutral-500);
  --icon-color-disabled: var(--color-neutral-400);
  --icon-color-brand: var(--color-yellow-500);
  --icon-color-inverse: var(--color-neutral-50);
}

/* SVG가 currentColor 사용 시 */
.icon {
  width: var(--icon-md);
  height: var(--icon-md);
  color: var(--icon-color-primary);
}

.icon-secondary {
  color: var(--icon-color-secondary);
}

---

9. 사용 원칙

9.1 일관성

• 한 화면에 사이즈 2가지 이내 — 너무 많은 사이즈가 섞이면 산만
• Stratis UI Icons만 사용 — 외부 아이콘 섞지 X. 스트로크 두께 차이로 일관성 깨짐
• 아이콘 + 텍스트는 색 통일 — 같은 그룹이면 같은 색

9.2 의미 전달

• 의미가 명확한 아이콘 선택 — heart = 즐겨찾기 vs 좋아요 같은 충돌 회피
• 아이콘만으로 의미 전달 X — 항상 라벨이나 컨텍스트와 함께
• Icon-only 버튼은 aria-label 필수 — 접근성 확보

9.3 강조 절제

• Filled는 아껴서 — 활성/강조 의미. 너무 많이 쓰면 시각적 무게감 ↑
• Brand 컬러 아이콘은 1-2개만 — 별점, Toast 액션 정도

9.4 터치 영역

• 아이콘 자체는 22-24px이지만 버튼 영역은 44×44px 이상 확보 (iOS 표준)
• 시각적 사이즈와 터치 영역은 다르다는 점 주의

---

10. Figma 워크플로 권장

10.1 Variables 구조

Yumyum/
├── 03-Icons/
│   ├── Size/
│   │   ├── icon-xs (12)
│   │   ├── icon-sm (16)
│   │   ├── icon-md (20)
│   │   ├── icon-lg (24)
│   │   └── icon-xl (32)
│   └── Color/
│       ├── icon-primary → neutral-800
│       ├── icon-secondary → neutral-500
│       ├── icon-disabled → neutral-400
│       ├── icon-brand → yellow-500
│       └── icon-inverse → neutral-50

10.2 Stratis UI Icons 활용

• Stratis 컴포넌트를 그대로 인스턴스로 사용
• 인스턴스 color override를 위 토큰으로 연결
• 사이즈 변경 시 Constraint로 비율 유지

---

11. 기존 vs 신규 비교

항목	기존	v2 (신규)
아이콘 라이브러리	즉흥적 사용	Stratis UI Icons로 통일
사이즈	정의 없음	4단계 (12/16/20/24/32)
색상	즉흥적	5단계 토큰 (neutral 기반)
Outline/Filled	구분 없음	명확한 사용 규칙
컴포넌트 매핑	없음	컴포넌트별 사이즈/컬러 명시
개발 워크플로	없음	SVG export 프로세스 정의

---

12. 다음 단계

Stratis UI Icons가 잡혔으니, 디자인 시스템 v2의 시각 요소 대부분이 정의됨. 남은 후속 작업:

• [ ] Motion — 애니메이션 duration, easing (transition, slide, fade)
• [ ] Empty/Loading/Error States — 빈 상태, 로딩, 에러 화면 가이드
• [ ] Accessibility Guidelines — 접근성 체크리스트
• [ ] 실제 화면 디자인 적용 — 만든 시스템으로 핵심 화면 만들기

---

이 문서는 살아있는 문서입니다. 새 아이콘 추가 시 함께 업데이트하세요.