korean-theming-standards

Korean Theming Standards Skill

Purpose

This skill ensures that all visual, cultural, and thematic elements in Black Trigram maintain authentic Korean cyberpunk aesthetics and respect traditional Korean martial arts philosophy throughout the codebase.

When to Apply

Automatically trigger this skill when:

• Creating or modifying UI components
• Adding visual effects or Three.js elements
• Implementing combat techniques or stances
• Working with text, labels, or descriptions
• Designing menus, HUDs, or overlays
• Adding color themes or styling
• Implementing Korean martial arts terminology
• Creating or modifying trigram stance systems
• Adding player archetypes or character attributes
• Reviewing pull requests with UI or cultural elements

Core Principles

1. Korean Color Palette (색상 체계)

ALWAYS use predefined KOREAN_COLORS constants:

✅ Primary Cyberpunk Colors (사이버펑크 주요 색상)

import { KOREAN_COLORS } from "@/types/constants/colors";

// PRIMARY COLORS - For main UI elements
KOREAN_COLORS.PRIMARY_CYAN      // 0x00e6e6 - Main UI accent
KOREAN_COLORS.PRIMARY_BLUE      // 0x0066ff - Interactive elements
KOREAN_COLORS.PRIMARY_RED       // 0xff4444 - Warnings, critical hits

// ACCENT COLORS - For emphasis and special effects
KOREAN_COLORS.ACCENT_GOLD       // 0xffc400 - Perfect strikes, highlights
KOREAN_COLORS.ACCENT_GREEN      // 0x44ff44 - Success, positive feedback
KOREAN_COLORS.ACCENT_PURPLE     // 0xaa44ff - Special effects, vital points

✅ Korean Traditional Colors (한국 전통 색상)

// Five Cardinal Colors (오방색) - Based on I Ching
KOREAN_COLORS.CARDINAL_EAST     // 0x00ff88 - 동방 청색 (East/Spring)
KOREAN_COLORS.CARDINAL_WEST     // 0xffffff - 서방 백색 (West/Autumn)
KOREAN_COLORS.CARDINAL_SOUTH    // 0xff4444 - 남방 적색 (South/Summer)
KOREAN_COLORS.CARDINAL_NORTH    // 0x000000 - 북방 흑색 (North/Winter)
KOREAN_COLORS.CARDINAL_CENTER   // 0xffaa00 - 중앙 황색 (Center/Earth)

✅ Trigram Stance Colors (팔괘 자세 색상)

// Eight Trigram colors for stance visualization
KOREAN_COLORS.TRIGRAM_GEON_PRIMARY    // 0xffd700 - ☰ Heaven (White/Gold)
KOREAN_COLORS.TRIGRAM_TAE_PRIMARY     // 0x87ceeb - ☱ Lake (Sky Blue)
KOREAN_COLORS.TRIGRAM_LI_PRIMARY      // 0xff4500 - ☲ Fire (Orange Red)
KOREAN_COLORS.TRIGRAM_JIN_PRIMARY     // 0x9370db - ☳ Thunder (Purple)
KOREAN_COLORS.TRIGRAM_SON_PRIMARY     // 0x32cd32 - ☴ Wind (Light Green)
KOREAN_COLORS.TRIGRAM_GAM_PRIMARY     // 0x1e90ff - ☵ Water (Blue)
KOREAN_COLORS.TRIGRAM_GAN_PRIMARY     // 0x8b4513 - ☶ Mountain (Brown)
KOREAN_COLORS.TRIGRAM_GON_PRIMARY     // 0x2f4f4f - ☷ Earth (Dark Gray)

✅ UI Background Colors (WCAG AA Compliant)

// Dark backgrounds for maximum text contrast
KOREAN_COLORS.UI_BACKGROUND_DARK      // 0x0a0a0a - Very dark (20.3:1 contrast)
KOREAN_COLORS.UI_BACKGROUND_MEDIUM    // 0x1a1a1a - Dark gray panels
KOREAN_COLORS.UI_BACKGROUND_LIGHT     // 0x2a2a2a - Medium dark cards

// Text colors (WCAG 2.1 Level AA - 4.5:1 minimum)
KOREAN_COLORS.TEXT_PRIMARY            // 0xffffff - White (20.3:1)
KOREAN_COLORS.TEXT_SECONDARY          // 0xcccccc - Light gray (13.1:1)
KOREAN_COLORS.TEXT_ACCENT             // 0x00e6e6 - Cyan emphasis (15.8:1)

2. Bilingual Text Requirements (이중 언어 요구사항)

ALL user-facing text MUST include Korean and English:

✅ Proper Bilingual Pattern

// GOOD: Korean | English format with proper spacing
interface BilingualText {
  readonly korean: string;
  readonly english: string;
}

// UI Component Example
<BilingualLabel 
  korean="건" 
  english="Heaven" 
  separator=" | "
/>

// Renders: "건 | Heaven"

✅ Combat Technique Names

interface Technique {
  readonly nameKorean: string;      // "천둥벽력"
  readonly nameEnglish: string;     // "Thunder Wall Strike"
  readonly nameHanja?: string;      // "天雷壁列" (optional Sino-Korean)
  readonly description: BilingualText;
}

// Example implementation
const technique: Technique = {
  nameKorean: "천둥벽력",
  nameEnglish: "Thunder Wall Strike",
  nameHanja: "天雷壁列",
  description: {
    korean: "하늘의 천둥 같은 강력한 벽력 공격",
    english: "Powerful thunder wall strike from heaven"
  }
};

✅ Vital Point Names (70 Points with Korean/English/TCM)

interface VitalPoint {
  readonly nameKorean: string;      // "백회"
  readonly nameEnglish: string;     // "Hundred Convergences"
  readonly nameTCM: string;         // "Baihui (GV20)"
  readonly location: string;        // Korean/English location description
}

// Example
const baihui: VitalPoint = {
  nameKorean: "백회",
  nameEnglish: "Hundred Convergences",
  nameTCM: "Baihui (GV20)",
  location: "정수리 중앙 | Crown of head center"
};

3. Korean Font Usage (한글 폰트 사용)

ALWAYS use FONT_FAMILY constants for Korean text:

✅ Font Family Standards

// ALWAYS import and use these constants
export const FONT_FAMILY = {
  KOREAN: "'Noto Sans KR', 'Malgun Gothic', sans-serif",
  ENGLISH: "'Roboto', 'Arial', sans-serif",
  MONOSPACE: "'Fira Code', 'Consolas', monospace",
} as const;

// Apply in components
<div style={{
  fontFamily: FONT_FAMILY.KOREAN,
  fontSize: '18px',
  fontWeight: 'bold',
  color: KOREAN_COLORS.TEXT_PRIMARY,
}}>
  {korean} | {english}
</div>

✅ Html Overlay with Korean Fonts

import { Html } from '@react-three/drei';
import { FONT_FAMILY, KOREAN_COLORS } from '@/types/constants';

<Html center position={[0, 2, 0]}>
  <div style={{
    fontFamily: FONT_FAMILY.KOREAN,
    fontSize: isMobile ? 14 : 18,
    color: KOREAN_COLORS.ACCENT_GOLD,
    fontWeight: 'bold',
    textAlign: 'center',
  }}>
    {korean} | {english}
  </div>
</Html>

4. Eight Trigram System Integration (팔괘 체계)

ALWAYS reference authentic I Ching trigrams:

✅ Trigram Stance Definitions

export const TRIGRAM_STANCES = {
  GEON: {
    symbol: "☰",
    korean: "건",
    english: "Heaven",
    hanja: "乾",
    element: "Metal",
    direction: "Northwest",
    philosophy: "Creative force, initiative, direct power",
    techniqueKorean: "천둥벽력",
    techniqueEnglish: "Thunder Wall Strike",
    color: KOREAN_COLORS.TRIGRAM_GEON_PRIMARY,
  },
  TAE: {
    symbol: "☱",
    korean: "태",
    english: "Lake",
    hanja: "兌",
    element: "Metal",
    direction: "West",
    philosophy: "Joyful, fluid movement, adaptability",
    techniqueKorean: "유수연타",
    techniqueEnglish: "Flowing Water Strike",
    color: KOREAN_COLORS.TRIGRAM_TAE_PRIMARY,
  },
  LI: {
    symbol: "☲",
    korean: "리",
    english: "Fire",
    hanja: "離",
    element: "Fire",
    direction: "South",
    philosophy: "Illumination, precision, clarity",
    techniqueKorean: "화염지창",
    techniqueEnglish: "Flame Spear",
    color: KOREAN_COLORS.TRIGRAM_LI_PRIMARY,
  },
  JIN: {
    symbol: "☳",
    korean: "진",
    english: "Thunder",
    hanja: "震",
    element: "Wood",
    direction: "East",
    philosophy: "Explosive energy, sudden action",
    techniqueKorean: "벽력일섬",
    techniqueEnglish: "Lightning Flash",
    color: KOREAN_COLORS.TRIGRAM_JIN_PRIMARY,
  },
  SON: {
    symbol: "☴",
    korean: "손",
    english: "Wind",
    hanja: "巽",
    element: "Wood",
    direction: "Southeast",
    philosophy: "Gentle persistence, penetration",
    techniqueKorean: "선풍연격",
    techniqueEnglish: "Whirlwind Strike",
    color: KOREAN_COLORS.TRIGRAM_SON_PRIMARY,
  },
  GAM: {
    symbol: "☵",
    korean: "감",
    english: "Water",
    hanja: "坎",
    element: "Water",
    direction: "North",
    philosophy: "Flow, adaptation, depth",
    techniqueKorean: "수류반격",
    techniqueEnglish: "Water Flow Counter",
    color: KOREAN_COLORS.TRIGRAM_GAM_PRIMARY,
  },
  GAN: {
    symbol: "☶",
    korean: "간",
    english: "Mountain",
    hanja: "艮",
    element: "Earth",
    direction: "Northeast",
    philosophy: "Stillness, immovability, defense",
    techniqueKorean: "반석방어",
    techniqueEnglish: "Mountain Defense",
    color: KOREAN_COLORS.TRIGRAM_GAN_PRIMARY,
  },
  GON: {
    symbol: "☷",
    korean: "곤",
    english: "Earth",
    hanja: "坤",
    element: "Earth",
    direction: "Southwest",
    philosophy: "Receptive, grounding, endurance",
    techniqueKorean: "대지포옹",
    techniqueEnglish: "Earth Embrace",
    color: KOREAN_COLORS.TRIGRAM_GON_PRIMARY,
  },
} as const;

5. Player Archetypes (플레이어 원형)

ALWAYS use authentic Korean character archetypes:

✅ Five Player Archetypes

export const PLAYER_ARCHETYPES = {
  MUSA: {
    korean: "무사",
    english: "Traditional Warrior",
    hanja: "武士",
    philosophy: "Honor through disciplined strength",
    combatStyle: "Balanced offense and defense",
    preferredStances: ["GEON", "GAN"],
  },
  AMSALJA: {
    korean: "암살자",
    english: "Shadow Assassin",
    hanja: "暗殺者",
    philosophy: "Precision through stealth",
    combatStyle: "Vital point targeting, critical strikes",
    preferredStances: ["LI", "SON"],
  },
  HACKER: {
    korean: "해커",
    english: "Cyber Warrior",
    hanja: "駭客",
    philosophy: "Technology-enhanced combat",
    combatStyle: "Analytical, exploit-focused",
    preferredStances: ["JIN", "GAM"],
  },
  JEONGBO_YOWON: {
    korean: "정보요원",
    english: "Intelligence Operative",
    hanja: "情報要員",
    philosophy: "Strategic analysis and adaptation",
    combatStyle: "Adaptive, counter-focused",
    preferredStances: ["GAM", "TAE"],
  },
  JOJIK_POKRYEOKBAE: {
    korean: "조직폭력배",
    english: "Organized Crime",
    hanja: "組織暴力輩",
    philosophy: "Ruthless pragmatism",
    combatStyle: "Aggressive, power-focused",
    preferredStances: ["GEON", "GON"],
  },
} as const;

6. Korean Martial Arts Terminology Accuracy

ALWAYS use authentic Korean martial arts terms:

✅ Combat Terminology

export const COMBAT_TERMS = {
  // Strikes (타격 기술)
  STRIKE: { korean: "타격", english: "Strike", hanja: "打擊" },
  PUNCH: { korean: "주먹", english: "Fist", hanja: "拳" },
  KICK: { korean: "차기", english: "Kick", hanja: "蹴" },
  
  // Defense (방어 

---

*Content truncated.*