# Archetype-FirstSpark 색상 시스템

## 1. 기반 패키지

```bash
yarn add @toss/tds-colors
```

`@toss/tds-colors`의 `adaptive` 네임스페이스를 기반으로, 게임 전용 시맨틱 토큰을 추가로 정의합니다.

---

## 2. 게임 시맨틱 색상 토큰

### 2-A. CSS 변수 정의

```css
/* src/styles/game-tokens.css */

/* ===== 라이트 모드 ===== */
:root {
  /* 골드 / 재화 */
  --color-gold-primary:      #FFD700;
  --color-gold-secondary:    #FFAA00;
  --color-gold-bg:           #FFF8E1;
  --color-gold-text:         #5A3200;

  /* 원소 등급 (Rarity) */
  --color-rarity-common:     #9E9E9E;
  --color-rarity-uncommon:   #4CAF50;
  --color-rarity-rare:       #2196F3;
  --color-rarity-epic:       #9C27B0;
  --color-rarity-legendary:  #FF9800;

  /* 합성 / 이벤트 */
  --color-fusion-primary:    #7C4DFF;
  --color-fusion-glow:       #B388FF;
  --color-enhance-primary:   #3182F6;
  --color-enhance-glow:      #90CAF9;

  /* 원소 — Tier 1 */
  --color-element-fire:      #FF4500;
  --color-element-water:     #1E90FF;
  --color-element-wind:      #87CEEB;
  --color-element-earth:     #8B4513;

  /* 원소 — Tier 2 */
  --color-element-steam:     #C0C0C0;
  --color-element-firestorm: #FF6347;
  --color-element-lava:      #FF2200;
  --color-element-storm:     #4169E1;
  --color-element-mud:       #8B6914;
  --color-element-desert:    #DEB887;

  /* 원소 — Tier 3 */
  --color-element-cloud:     #87CEEB;
  --color-element-lightning: #FFD700;
  --color-element-volcano:   #CC2200;
  --color-element-rainbow:   #FF69B4;
  --color-element-obsidian:  #1C1C1C;

  /* 원소 — Tier 4 */
  --color-element-thunderstorm: #191970;
  --color-element-crystal:   #9400D3;
  --color-element-life:      #00FF7F;
  --color-element-aurora:    #7DF9FF;

  /* 원소 — Tier 5 */
  --color-element-creation:  #FFFFFF;
  --color-element-spirit:    #FFD700;

  /* 카드 상태 */
  --color-card-bg-obtained:  #FFFFFF;
  --color-card-bg-locked:    var(--tds-adaptive-greyBackground);
  --color-card-border-obtained: var(--tds-adaptive-grey200);
  --color-card-border-locked:   var(--tds-adaptive-grey200);

  /* 오프라인 보상 */
  --color-offline-bg:        #FFFFFF;
  --color-offline-overlay:   rgba(0, 0, 0, 0.55);
  --color-offline-reward-bg: #F7F8FA;
  --color-offline-btn-from:  #3182F6;
  --color-offline-btn-to:    #6C4DE6;
}

/* ===== 다크 모드 ===== */
@media (prefers-color-scheme: dark) {
  :root {
    /* 골드 / 재화 */
    --color-gold-bg:           #2A2000;
    --color-gold-text:         #FFD97A;

    /* 원소 등급 (채도 약간 낮춤, 다크에서 과도한 채도 방지) */
    --color-rarity-common:     #BDBDBD;
    --color-rarity-uncommon:   #66BB6A;
    --color-rarity-rare:       #42A5F5;
    --color-rarity-epic:       #BA68C8;
    --color-rarity-legendary:  #FFA726;

    /* 합성 / 이벤트 */
    --color-fusion-primary:    #9575CD;
    --color-fusion-glow:       #D1C4E9;
    --color-enhance-primary:   #5C9EE8;
    --color-enhance-glow:      #BBDEFB;

    /* 카드 상태 */
    --color-card-bg-obtained:  #1E1E1E;
    --color-card-bg-locked:    #2A2A2A;

    /* 오프라인 보상 */
    --color-offline-bg:        #1E1E1E;
    --color-offline-overlay:   rgba(0, 0, 0, 0.72);
    --color-offline-reward-bg: #2A2A2A;
  }
}
```

---

## 3. TypeScript 토큰 상수

```ts
// src/styles/gameColors.ts
import { adaptive } from '@toss/tds-colors';

/** 게임 전용 시맨틱 색상 상수 */
export const gameColors = {
  // ── 재화 ──────────────────────────────────────────────
  goldPrimary:    '#FFD700',
  goldSecondary:  '#FFAA00',
  goldBg:         '#FFF8E1',      // 다크: var(--color-gold-bg) 사용
  goldText:       '#5A3200',

  // ── 등급 ──────────────────────────────────────────────
  rarityCommon:    '#9E9E9E',
  rarityUncommon:  '#4CAF50',
  rarityRare:      '#2196F3',
  rarityEpic:      '#9C27B0',
  rarityLegendary: '#FF9800',

  // ── 이벤트 ────────────────────────────────────────────
  fusionPrimary:   '#7C4DFF',
  fusionGlow:      '#B388FF',
  enhancePrimary:  '#3182F6',
  enhanceGlow:     '#90CAF9',

  // ── 원소별 주요 색 ─────────────────────────────────────
  elements: {
    fire:         '#FF4500',
    water:        '#1E90FF',
    wind:         '#87CEEB',
    earth:        '#8B4513',
    steam:        '#C0C0C0',
    firestorm:    '#FF6347',
    lava:         '#FF2200',
    storm:        '#4169E1',
    mud:          '#8B6914',
    desert:       '#DEB887',
    cloud:        '#87CEEB',
    fog:          '#DCDCDC',
    volcano:      '#CC2200',
    rainbow:      '#FF69B4',
    obsidian:     '#1C1C1C',
    ash:          '#696969',
    lightning:    '#FFD700',
    tsunami:      '#006994',
    ceramic:      '#D2691E',
    dust:         '#BC8F5F',
    oasis:        '#228B22',
    glass:        '#E0FFFF',
    thunderstorm: '#191970',
    island:       '#3CB371',
    crystal:      '#9400D3',
    life:         '#00FF7F',
    magnet:       '#A9A9A9',
    aurora:       '#7DF9FF',
    creation:     '#FFFFFF',
    spirit:       '#FFD700',
  },

  // ── TDS Adaptive 색 (자주 쓰는 것만 재노출) ─────────────
  bg:             adaptive.background,
  greyBg:         adaptive.greyBackground,
  grey200:        adaptive.grey200,
  grey400:        adaptive.grey400,
  grey500:        adaptive.grey500,
  grey900:        adaptive.grey900,
  blue500:        adaptive.blue500,
} as const;

/** 등급 → 색상 매핑 헬퍼 */
export function rarityColor(rarity: string): string {
  return {
    common:    gameColors.rarityCommon,
    uncommon:  gameColors.rarityUncommon,
    rare:      gameColors.rarityRare,
    epic:      gameColors.rarityEpic,
    legendary: gameColors.rarityLegendary,
  }[rarity] ?? gameColors.rarityCommon;
}

/** 원소 ID → 주요 색상 헬퍼 */
export function elementColor(id: string): string {
  return gameColors.elements[id as keyof typeof gameColors.elements] ?? '#888888';
}
```

---

## 4. 다크모드 대응 규칙

| 규칙 | 설명 |
|------|------|
| 배경/텍스트 | `adaptive.*` 사용 (자동 대응) |
| 원소 고유 컬러 | 다크모드에서 그대로 사용 (원소 아이덴티티 유지) |
| 골드/재화 | CSS 변수 `--color-gold-*` 사용 (다크에서 어두운 배경) |
| 이펙트/글로우 | 다크에서 밝기 70~80%로 감소 (눈부심 방지) |
| 오버레이 | 다크에서 `rgba(0,0,0,0.72)` (라이트보다 진하게) |

### emotion/css에서 다크모드 처리 패턴

```tsx
import { css } from '@emotion/react';
import { adaptive } from '@toss/tds-colors';

// adaptive를 사용하면 다크모드 자동 대응
const cardStyle = css`
  background: ${adaptive.background};
  color: ${adaptive.grey900};
  border: 1px solid ${adaptive.grey200};
`;

// 게임 전용 색은 CSS 변수 사용
const goldBadgeStyle = css`
  background: linear-gradient(135deg, var(--color-gold-primary), var(--color-gold-secondary));
  color: var(--color-gold-text);
`;
```

---

## 5. 색상 접근성 체크리스트

- [ ] 텍스트 대비비 4.5:1 이상 (WCAG AA)
- [ ] 색 외 다른 시각적 단서 병행 (아이콘, 패턴)
- [ ] 등급 구분: 색 + 배지 텍스트 병행
- [ ] 원소 카드: 색 + 이모지 병행
