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 (사이버펑크 주요 색상)** ```typescript 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 (한국 전통 색상)** ```typescript // 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 (팔괘 자세 색상)** ```typescript // 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)** ```typescript // 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** ```typescript // 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** ```typescript 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)** ```typescript 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** ```typescript // 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** ```typescript 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** ```typescript 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** ```typescript 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** ```typescript export const COMBAT_TERMS = { // Strikes (타격 기술) STRIKE: { korean: "타격", english: "Strike", hanja: "打擊" }, PUNCH: { korean: "주먹", english: "Fist", hanja: "拳" }, KICK: { korean: "차기", english: "Kick", hanja: "蹴" }, // Defense (방어 기술) BLOCK: { korean: "막기", english: "Block", hanja: "防禦" }, DODGE: { korean: "회피", english: "Dodge", hanja: "回避" }, COUNTER: { korean: "반격", english: "Counter", hanja: "反擊" }, // Vital Points (급소) VITAL_POINT: { korean: "급소", english: "Vital Point", hanja: "急所" }, PRESSURE_POINT: { korean: "경혈", english: "Acupoint", hanja: "經穴" }, // Stances (자세) STANCE: { korean: "자세", english: "Stance", hanja: "姿勢" }, READY_POSITION: { korean: "준비자세", english: "Ready Position" }, // Energy (기) KI: { korean: "기", english: "Ki Energy", hanja: "氣" }, FOCUS: { korean: "집중", english: "Focus", hanja: "集中" }, // Techniques (기술) TECHNIQUE: { korean: "기술", english: "Technique", hanja: "技術" }, SPECIAL_MOVE: { korean: "필살기", english: "Special Move", hanja: "必殺技" }, } as const; ``` ### 7. Common Theming Anti-Patterns to REJECT **Immediately flag and reject these patterns:** ❌ **Hard-coded Colors Instead of Constants** ```typescript // BAD: Hard-coded hex color <div style={{ color: '#00ffff' }}>Text</div> // GOOD: Use KOREAN_COLORS constant