Gnuboard7/docs/frontend/dark-mode.md

다크 모드 지원 (engine-v1.1.0+)

상위 문서: 프론트엔드 가이드 인덱스

그누보드7 템플릿 시스템은 Tailwind CSS dark mode variant를 활용하여 다크 모드를 전면 지원합니다.

---

TL;DR (5초 요약)

1. Tailwind dark: variant 사용 (예: bg-white dark:bg-gray-800)
2. 배경: bg-white dark:bg-gray-800/900
3. 텍스트: text-gray-900 dark:text-white
4. 테두리: border-gray-200 dark:border-gray-700
5. 항상 light/dark 쌍으로 지정 필수!

---

템플릿별 지원 현황

템플릿 식별자	features.dark_mode	설명
sirsoft-admin_basic	미선언	ThemeToggle 존재, dark: variant 동작
sirsoft-basic	true	template.json에 선언, 완전 지원

상세 컴포넌트 목록: sirsoft-admin_basic, sirsoft-basic

---

목차

1. 다크 모드 설정
2. 컴포넌트 다크 모드 적용 규칙
3. 컴포넌트 개발 예시
4. 레이아웃 JSON에서 다크 모드 사용
5. ThemeToggle 컴포넌트
6. 기존 컴포넌트 재사용 이점
7. 컴포넌트 개발 체크리스트
8. 테스트 요구사항
9. 주의사항
10. 참고 자료

---

1. 다크 모드 설정

main.css에 다크 모드 variant 정의:

@variant dark (.dark &);

동작 원리:

• document.documentElement.classList.add('dark'): 다크 모드 활성화
• document.documentElement.classList.remove('dark'): 라이트 모드 활성화
• Tailwind CSS가 .dark 클래스 감지하여 dark: variant 적용

---

2. 컴포넌트 다크 모드 적용 규칙

모든 composite 및 layout 컴포넌트는 다크 모드를 지원해야 합니다.

핵심 규칙

주의: 다크 모드 전용 색상만 하드코딩 금지 (예: border-gray-700만 사용)
필수: light와 dark variant 항상 함께 지정
✅ 필수: 기존 색상 매핑 규칙 준수
✅ 필수: Tailwind CSS 유틸리티 클래스 사용

색상 매핑 규칙

Light 모드	Dark 모드	용도
bg-white	dark:bg-gray-800	카드, 모달, 드롭다운 배경
bg-gray-50	dark:bg-gray-700	헤더, 서브 배경
bg-gray-100	dark:bg-gray-700	호버 배경
border-gray-200	dark:border-gray-700	주요 테두리
border-gray-300	dark:border-gray-600	입력 필드 테두리
text-gray-900	dark:text-white	제목, 중요 텍스트
text-gray-700	dark:text-gray-300	본문 텍스트
text-gray-600	dark:text-gray-400	보조 텍스트
text-gray-400	dark:text-gray-500	비활성화, 플레이스홀더

투명도 표현

색상 강조가 필요하지만 너무 진하지 않아야 할 경우 /20 투명도 사용:

// ✅ DO: 투명도로 강조 색상 표현
'bg-green-50 dark:bg-green-900/20'
'text-green-700 dark:text-green-400'
'border-green-200 dark:border-green-800'

// Success 상태
'bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-400'

// Warning 상태
'bg-yellow-50 dark:bg-yellow-900/20 text-yellow-700 dark:text-yellow-400'

// Error 상태
'bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-400'

액센트 색상

브랜드 색상(blue, red 등)은 다크 모드에서 약간 밝게 조정:

// Primary 버튼
'bg-blue-600 dark:bg-blue-500'
'hover:bg-blue-700 dark:hover:bg-blue-600'

// 링크 텍스트
'text-blue-600 dark:text-blue-400'

// 테두리
'border-blue-600 dark:border-blue-400'

---

3. 컴포넌트 개발 예시

올바른 예

// ✅ DO: 다크 모드 지원
import { Div } from '../basic/Div';
import { H2 } from '../basic/H2';
import { P } from '../basic/P';

export const Card: React.FC<CardProps> = ({ title, content }) => {
  return (
    <Div className="bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700 rounded-lg p-4">
      <H2 className="text-gray-900 dark:text-white font-bold mb-2">
        {title}
      </H2>
      <P className="text-gray-600 dark:text-gray-400">
        {content}
      </P>
    </Div>
  );
};

잘못된 예

// ❌ DON'T: 다크 모드 미지원
export const Card: React.FC<CardProps> = ({ title, content }) => {
  return (
    <Div className="bg-white border border-gray-200 rounded-lg p-4">
      <H2 className="text-gray-900 font-bold mb-2">{title}</H2>
      <P className="text-gray-600">{content}</P>
    </Div>
  );
};

// ❌ DON'T: 다크 모드 전용 색상만 하드코딩
export const Card: React.FC<CardProps> = ({ title, content }) => {
  return (
    <Div className="bg-gray-800 border border-gray-700 rounded-lg p-4">
      <H2 className="text-white font-bold mb-2">{title}</H2>
      <P className="text-gray-400">{content}</P>
    </Div>
  );
};

---

4. 레이아웃 JSON에서 다크 모드 사용

{
  "type": "Div",
  "props": {
    "className": "bg-white dark:bg-gray-800 p-4 rounded-lg border border-gray-200 dark:border-gray-700"
  },
  "children": [
    {
      "type": "H2",
      "props": {
        "className": "text-gray-900 dark:text-white font-bold mb-2",
        "text": "$t:dashboard.title"
      }
    },
    {
      "type": "P",
      "props": {
        "className": "text-gray-600 dark:text-gray-400",
        "text": "{{stats.description}}"
      }
    }
  ]
}

---

5. ThemeToggle 컴포넌트

다크 모드 전환은 ThemeToggle composite 컴포넌트를 사용:

{
  "type": "composite",
  "name": "ThemeToggle",
  "props": {
    "className": "p-2"
  }
}

ThemeToggle 동작:

• 클릭 시 document.documentElement.classList.toggle('dark') 실행
• localStorage에 사용자 선호도 저장 (theme 키)
• 페이지 로드 시 저장된 테마 자동 적용

---

6. 기존 컴포넌트 재사용 이점

모든 그누보드7 기본 composite 컴포넌트는 다크 모드를 지원합니다.

UI 컴포넌트

• ActionMenu, Alert, AlertDialog, Breadcrumb, Card, CodeEditor
• ConfirmDialog, DataGrid, Dialog, Dropdown, EmptyState
• IconButton, LoadingSpinner, Modal, Pagination, SearchBar
• StatCard, StatusBadge, TabNavigation, Toast
• ProductCard, TemplateCard, FilterGroup

관리자 컴포넌트

• AdminHeader, AdminFooter, AdminSidebar, NotificationCenter
• UserProfile, PageHeader, LayoutEditorHeader, LayoutFileList
• LayoutHistoryPanel

Layout 컴포넌트

• Container, Flex, Grid, Section, ThreeColumnLayout

✅ 기존 컴포넌트 재사용 시 자동으로 다크 모드가 지원되므로, 신규 개발보다 재사용을 우선하세요.

---

7. 컴포넌트 개발 체크리스트

새로운 컴포넌트 개발 시 다음 사항을 확인하세요:

□ 기본 컴포넌트만 사용 (HTML 태그 직접 사용 금지)
□ 기존 composite 컴포넌트 재사용 검토
□ 모든 배경색에 dark: variant 추가
□ 모든 텍스트 색상에 dark: variant 추가
□ 모든 테두리 색상에 dark: variant 추가
□ 색상 매핑 규칙 준수
□ 라이트 모드에서 정상 표시 확인
□ 다크 모드 전환 시 정상 표시 확인
□ 다국어 처리
□ TypeScript 타입 정의
□ 단위 테스트 작성

---

8. 테스트 요구사항

다크 모드를 지원하는 컴포넌트 개발 시:

1. 라이트 모드 테스트: 모든 요소가 적절히 표시되는지 확인
2. 다크 모드 전환 테스트: ThemeToggle 클릭 시 모든 요소가 변경되는지 확인
3. 색상 대비율 검증: WCAG 2.1 AA 기준 충족 여부 검토 (선택)

---

9. 주의사항

주의 사항

• 다크 모드 전용 색상만 하드코딩 (예: border-gray-700만 사용)
• 인라인 스타일로 색상 지정 (style={{ color: '#000' }})
• JavaScript로 색상 동적 변경 (Tailwind 사용)

필수

• 항상 light와 dark variant 함께 지정
• Tailwind CSS 유틸리티 클래스 사용
• 기존 색상 매핑 규칙 준수
• 기존 컴포넌트 재사용 우선

---

10. 참고 자료

• Tailwind CSS Dark Mode 공식 문서: https://tailwindcss.com/docs/dark-mode

• 템플릿 예시: templates/sirsoft-admin_basic/src/components/composite/

---

관련 문서

• 컴포넌트 개발 규칙 - 기본/집합/레이아웃 컴포넌트
• 반응형 레이아웃 - Tailwind breakpoint 활용
• 템플릿 개발 가이드라인 - 빌드 및 테스트