kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ERP-node/docs/shadcn-ui-레이아웃-패턴-분석-보고서.md

19 KiB
Raw Blame History

shadcn/ui 레이아웃 패턴 적용 상태 분석 보고서

📋 분석 목적

프로젝트의 컴포넌트들이 shadcn/ui의 레이아웃 패턴을 정확하게 따르고 있는지 확인하고, 개선이 필요한 부분을 식별합니다.

✅ 잘 적용된 부분

1. Card 컴포넌트 구조 ✅

shadcn/ui 공식 패턴:

<Card>
  <CardHeader>
    <CardTitle>제목</CardTitle>
    <CardDescription>설명</CardDescription>
  </CardHeader>
  <CardContent>{/* 내용 */}</CardContent>
  <CardFooter>{/* 액션 버튼들 */}</CardFooter>
</Card>

적용 현황:

  • ✅ CardRenderer.tsx에서 CardHeader, CardContent, CardFooter를 올바르게 사용
  • ✅ FlowVisibilityConfigPanel.tsx에서 Card 구조를 정확히 따름
  • ✅ EnhancedInteractiveScreenViewer.tsx에서 Card 패턴 사용

2. 간격 시스템 (Spacing) ✅

shadcn/ui 권장 간격:

  • 카드 패딩: p-6 (24px)
  • 카드 간 마진: gap-6 (24px)
  • 폼 필드 간격: space-y-4 (16px)
  • 섹션 간격: space-y-8 (32px)

적용 현황:

  • ✅ FlowVisibilityConfigPanel.tsx에서 space-y-4, space-y-2 사용
  • ✅ MultiApiConfig.tsx에서 space-y-2, space-y-3, space-y-4 적절히 사용
  • ✅ 대부분의 컴포넌트에서 Tailwind spacing scale 준수

3. 타이포그래피 ✅

shadcn/ui 권장 타이포그래피:

  • 페이지 제목: text-3xl font-bold
  • 섹션 제목: text-2xl font-semibold
  • 카드 제목: text-xl font-semibold
  • 본문 텍스트: text-sm text-muted-foreground

적용 현황:

  • ✅ CardRenderer.tsx에서 text-lg 사용 (카드 제목)
  • ✅ FlowVisibilityConfigPanel.tsx에서 text-xs font-medium 사용 (라벨)
  • ✅ 대부분의 컴포넌트에서 적절한 타이포그래피 사용

⚠️ 개선이 필요한 부분

1. Card 컴포넌트 패딩 중복 ❌

문제점:

// ❌ 잘못된 사용 (CardRenderer.tsx:28)
<CardContent className="flex-1 p-4">{/* 내용 */}</CardContent>

문제:

  • CardContent는 이미 px-6 패딩을 포함하고 있음
  • 추가로 p-4를 적용하면 중복 패딩이 발생
  • shadcn/ui Card 컴포넌트 구조를 위반

올바른 사용:

// ✅ 올바른 사용
<CardContent className="flex-1">{/* 내용 */}</CardContent>

수정 필요 파일:

  • frontend/lib/registry/components/CardRenderer.tsx (line 28)

2. 하드코딩된 색상 사용 ❌

문제점:

// ❌ 잘못된 사용 (CardRenderer.tsx:33-36)
<div className="flex h-full items-start text-sm text-gray-700">
  <div className="w-full">
    <div className="mb-2 font-medium">{content}</div>
    <div className="text-xs text-gray-500">
      실제 할당된 화면에서 표시되는 카드입니다.
    </div>
  </div>
</div>

문제:

  • text-gray-700, text-gray-500, text-gray-600, text-gray-400 사용
  • CSS 변수 기반 색상 시스템을 사용하지 않음

올바른 사용:

// ✅ 올바른 사용
<div className="flex h-full items-start text-sm text-foreground">
  <div className="w-full">
    <div className="mb-2 font-medium">{content}</div>
    <div className="text-xs text-muted-foreground">
      실제 할당된 화면에서 표시되는 카드입니다.
    </div>
  </div>
</div>

수정 필요 파일:

  • frontend/lib/registry/components/CardRenderer.tsx (lines 33-36, 44)
  • frontend/components/screen/config-panels/FlowVisibilityConfigPanel.tsx (line 356: text-green-500)

3. 인라인 스타일로 색상 지정 ❌

문제점:

// ❌ 잘못된 사용 (CardDisplayComponent.tsx:190-191)
borderColor: isSelected ? "#3b82f6" : "#cbd5e1",

문제:

  • 인라인 스타일로 색상 하드코딩
  • CSS 변수를 사용하지 않음

올바른 사용:

// ✅ 올바른 사용
className={cn(
  "border",
  isSelected ? "border-ring" : "border-border"
)}

수정 필요 파일:

  • frontend/lib/registry/components/card-display/CardDisplayComponent.tsx (lines 190-191)

4. Card 컴포넌트 기본 패딩 변경 ❌

문제점: shadcn/ui의 Card 컴포넌트는 기본적으로:

  • Card: py-6 (상하 패딩만)
  • CardHeader: px-6 (좌우 패딩만)
  • CardContent: px-6 (좌우 패딩만)
  • CardFooter: px-6 (좌우 패딩만)

하지만 일부 컴포넌트에서 추가 패딩을 적용하여 구조를 변경하고 있음

5. 반응형 디자인 미적용 ⚠️

문제점: 일부 컴포넌트에서 반응형 클래스를 사용하지 않고 고정 크기 사용

권장사항:

// ✅ 올바른 반응형 패턴
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">

📊 종합 평가

적용률

항목 상태 비율
Card 구조 사용 ✅ 양호 ~90%
간격 시스템 ✅ 양호 ~85%
타이포그래피 ✅ 양호 ~80%
색상 시스템 ⚠️ 개선 필요 ~60%
패딩 중복 ❌ 문제 있음 ~30%
반응형 디자인 ⚠️ 개선 필요 ~50%

우선순위별 개선 사항

Priority 1: 긴급 수정 필요

  1. CardContent 패딩 중복 제거
  2. 하드코딩된 색상 교체

Priority 2: 중간 우선순위

  1. 인라인 스타일 색상 제거
  2. 반응형 디자인 적용

Priority 3: 점진적 개선

  1. Card 컴포넌트 구조 표준화
  2. 타이포그래피 일관성 개선

🔧 권장 수정 사항

1. CardRenderer.tsx 수정

// 현재
<CardContent className="flex-1 p-4">
  <div className="flex h-full items-start text-sm text-gray-700">
    <div className="text-xs text-gray-500">...</div>
  </div>
</CardContent>

// 수정 후
<CardContent className="flex-1">
  <div className="flex h-full items-start text-sm text-foreground">
    <div className="text-xs text-muted-foreground">...</div>
  </div>
</CardContent>

2. CardDisplayComponent.tsx 수정

// 현재
borderColor: isSelected ? "#3b82f6" : "#cbd5e1",

// 수정 후
className={cn(
  "border",
  isSelected ? "border-ring" : "border-border"
)}

3. FlowVisibilityConfigPanel.tsx 수정

// 현재
<CheckCircle className="ml-auto h-4 w-4 text-green-500" />

// 수정 후
<CheckCircle className="ml-auto h-4 w-4 text-success" />

📝 체크리스트

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

  • Card 컴포넌트 사용 시 CardHeader, CardContent, CardFooter 구조 준수
  • CardContent에 추가 패딩(p-*) 적용하지 않기
  • 하드코딩된 색상(text-gray-*, bg-gray-*) 사용하지 않기
  • CSS 변수 기반 색상(text-foreground, bg-background 등) 사용
  • 간격 시스템(space-y-*, gap-*) Tailwind scale 준수
  • 타이포그래피 shadcn/ui 가이드라인 준수
  • 반응형 디자인 적용 (sm:, md:, lg: 브레이크포인트)

🎯 결론

전반적으로 shadcn/ui의 레이아웃 패턴을 잘 따르고 있지만, 일부 컴포넌트에서:

  1. 패딩 중복 문제가 발견됨
  2. 하드코딩된 색상 사용이 여전히 존재함
  3. 반응형 디자인 적용이 부족함

이러한 부분들을 수정하면 더욱 일관된 shadcn/ui 디자인 시스템을 유지할 수 있습니다.

✅ 수정 완료 내역

2024년 수정 사항

CardContent 패딩 중복 제거

  • ✅ CardRenderer.tsx: p-4 제거
  • ✅ SplitPanelLayoutComponent.tsx: p-2, p-4 제거, 내부 요소에 패딩 적용
  • ✅ MailDesigner.tsx: CardHeader, CardContent 패딩 제거
  • ✅ TemplateManager.tsx: CardContent 패딩 제거, 내부 요소에 적용
  • ✅ FileComponentConfigPanel.tsx: CardContent 패딩 제거, 내부 요소에 적용

하드코딩된 색상 교체

  • ✅ CardRenderer.tsx: text-gray-* → text-foreground, text-muted-foreground
  • ✅ FlowVisibilityConfigPanel.tsx: text-green-500 → text-success
  • ✅ SplitPanelLayoutComponent.tsx: 모든 text-gray-*, bg-gray-* 교체
  • ✅ FlowToolbar.tsx: bg-gray-200 → bg-border, text-red-* → text-destructive
  • ✅ ValidationNotification.tsx: 모든 하드코딩 색상을 CSS 변수로 교체
  • ✅ InteractiveScreenViewer.tsx: text-gray-500, bg-white 교체
  • ✅ ScreenDesigner.tsx: text-gray-600 → text-muted-foreground
  • ✅ MailDesigner.tsx: text-gray-*, bg-white 교체
  • ✅ TemplateManager.tsx: text-gray-* 교체
  • ✅ FileComponentConfigPanel.tsx: 모든 하드코딩 색상 교체

인라인 스타일 색상 제거

  • ✅ CardDisplayComponent.tsx: 인라인 스타일 색상을 CSS 변수로 교체

아직 수정이 필요한 파일들

다음 파일들은 특수한 케이스로 판단되어 추가 검토가 필요합니다:

  1. DataflowVisualization.tsx: CardContent에 p-4 사용 (특수 레이아웃)
  2. ActionConfigStep.tsx: CardContent에 p-0 사용 (전체 너비 필요)
  3. ControlConditionStep.tsx: CardContent에 p-0 사용 (전체 너비 필요)
  4. MultiActionConfigStep.tsx: CardContent에 p-4 사용 (특수 레이아웃)
  5. ScreenPreview.tsx: CardContent에 p-0 사용 (전체 너비 필요)

이러한 파일들은 각각의 특수한 레이아웃 요구사항 때문에 기본 패딩을 오버라이드하는 것이 필요할 수 있습니다.

관리자 테이블 표준화 완료

수정된 테이블 컴포넌트들

주요 파일들:

  • ✅ MenuTable.tsx: 하드코딩 색상 교체, 표준 헤더/행 스타일 적용

    • bg-gray-50 → bg-muted/50
    • text-gray-* → text-foreground, text-muted-foreground
    • hover:bg-gray-* → hover:bg-muted, hover:bg-muted/50
    • text-green-600 → text-success
    • bg-gray-900 → bg-popover
    • 레벨 배지와 상태 배지 색상을 CSS 변수로 교체
    • 테이블 헤더/행에 표준 높이 및 스타일 적용 (h-12, h-16, border-b, transition-colors)

  • ✅ UserAuthTable.tsx: 권한 배지 하드코딩 색상 교체

    • bg-purple-100, bg-blue-100, bg-gray-100 등 → CSS 변수로 교체
    • bg-primary/20, bg-success/20, bg-warning/20 등으로 통일

  • ✅ MenuPermissionsTable.tsx: 테이블 셀 높이 및 텍스트 크기 표준화

    • 모든 TableCell에 h-16 및 text-sm 적용
    • 헤더 이미 표준 준수 확인

  • ✅ ColumnDefinitionTable.tsx: 테이블 구조 표준화

    • 테이블 헤더에 h-12, bg-muted/50, font-semibold, text-sm 적용
    • 테이블 행에 h-16, border-b, hover:bg-muted/50, transition-colors 적용
    • 모든 TableCell에 h-16, text-sm 적용
    • text-red-500 → text-destructive
    • 테이블 컨테이너에 bg-card shadow-sm 추가

  • ✅ UserTable.tsx: 이미 표준 준수 확인 (h-12, bg-muted/50, h-16, border-b, transition-colors)

  • ✅ CompanyTable.tsx: 이미 표준 준수 확인 (h-12, bg-muted/50, h-16, border-b, transition-colors)

  • ✅ RestApiConnectionList.tsx: 이미 표준 준수 확인

표준 적용 요약:

항목 표준 값 적용 상태
테이블 헤더 h-12 bg-muted/50 font-semibold text-sm ✅ 완료
테이블 행 h-16 border-b hover:bg-muted/50 transition-colors ✅ 완료
테이블 셀 h-16 text-sm ✅ 완료
테이블 컨테이너 rounded-lg border bg-card shadow-sm ✅ 완료
색상 시스템 CSS 변수 사용 (하드코딩 금지) ✅ 완료

테이블 테두리 및 라운드 수정 완료

수정 내용

기본 Table 컴포넌트 (frontend/components/ui/table.tsx):

  • ✅ TableRow: 행 구분선(border-b) 다시 추가 - 각 데이터 행 사이 구분선 유지
  • ✅ TableHeader: 헤더 구분선([&_tr]:border-b) 추가 - 헤더와 본문 구분

테이블 컨테이너 라운드 제거:

  • ✅ 모든 테이블 컨테이너의 rounded-lg 제거
  • ✅ 테이블 컨테이너의 외곽 border 제거 (이미 완료)

수정된 컴포넌트들:

  • ✅ UserTable.tsx: rounded-lg 제거
  • ✅ CompanyTable.tsx: rounded-lg 제거, 스켈레톤의 border 및 border-b 제거
  • ✅ MenuTable.tsx: rounded-lg 제거
  • ✅ ColumnDefinitionTable.tsx: rounded-lg 제거
  • ✅ UserAuthTable.tsx: rounded-lg 제거
  • ✅ MenuPermissionsTable.tsx: rounded-lg 제거
  • ✅ RestApiConnectionList.tsx: rounded-lg 제거
  • ✅ FlowWidget.tsx: 테이블 컨테이너의 rounded-lg 및 border 제거, 헤더와 셀의 border-b 유지 (행 구분선)
  • ✅ ListTestWidget.tsx: rounded-lg 제거
  • ✅ 기타 위젯 테이블: rounded-lg 제거

수정 요약:

항목 변경 내용 적용 상태
행 구분선 TableRow에 border-b 추가 (데이터 행 사이 구분) ✅ 완료
헤더 구분선 TableHeader에 [&_tr]:border-b 추가 ✅ 완료
테이블 컨테이너 라운드 모든 rounded-lg 제거 ✅ 완료
테이블 컨테이너 테두리 모든 외곽 border 제거 (이미 완료) ✅ 완료

결과:

  • 각 데이터 행 사이에 구분선(border-b)이 표시되어 행 구분이 명확합니다
  • 테이블 컨테이너는 라운드 없이 직각으로 표시됩니다
  • 테이블 외곽 테두리는 없지만, 행 구분선으로 데이터 구분이 가능합니다
  • 시각적으로 깔끔하면서도 데이터 구분이 명확한 디자인이 적용되었습니다

최종 적용률 업데이트

항목 상태 비율
Card 구조 사용 ✅ 양호 ~95%
간격 시스템 ✅ 양호 ~90%
타이포그래피 ✅ 양호 ~85%
색상 시스템 ✅ 완료 ~98%
패딩 중복 ✅ 대부분 수정 ~90%
반응형 디자인 ✅ 개선됨 ~75%
테이블 표준화 ✅ 완료 ~95%
테이블 테두리 및 라운드 수정 ✅ 완료 ~100%

추가 완료된 작업

하드코딩 색상 추가 교체 완료

주요 파일들:

  • ✅ FileComponentConfigPanel.tsx: text-gray-900 → text-foreground, text-blue-* → text-primary
  • ✅ ButtonConfigPanel.tsx: 모든 text-gray-*, bg-gray-*, hover:bg-gray-* 교체
  • ✅ UnifiedPropertiesPanel.tsx: 모든 text-gray-*, border-gray-* 교체
  • ✅ app/(main)/admin/page.tsx: 전체 페이지 하드코딩 색상 교체
  • ✅ CardDisplayComponent.tsx: 모든 text-gray-*, bg-gray-*, 인라인 색상 교체
  • ✅ getComponentConfigPanel.tsx: 로딩 상태 하드코딩 색상 교체
  • ✅ DynamicComponentRenderer.tsx: 플레이스홀더 하드코딩 색상 교체
  • ✅ SplitPanelLayoutComponent.tsx: 빈 상태 텍스트 색상 교체
  • ✅ TemplateManager.tsx: 빈 상태 및 검색 아이콘 색상 교체
  • ✅ MailDesigner.tsx: 컴포넌트 타입 색상 및 빈 상태 색상 교체

다음 단계

  1. 반응형 디자인 적용: 모바일/태블릿/데스크톱 브레이크포인트 적용 (진행 중)
  2. 특수 케이스 검토: p-0을 사용하는 컴포넌트들에 대한 표준화 (완료)
  3. 일관성 검증: 새로운 컴포넌트 개발 시 가이드라인 준수 확인 (완료)

완료된 작업 요약

하드코딩된 색상 교체 완료

특수 케이스 파일들:

  • ✅ DataflowVisualization.tsx: 모든 하드코딩 색상을 CSS 변수로 교체

    • text-gray-* → text-foreground, text-muted-foreground
    • bg-blue-* → bg-primary/10, border-primary
    • bg-yellow-* → bg-warning/10, border-warning
    • bg-green-* → bg-success/10, text-success
    • bg-red-* → bg-destructive/10, text-destructive
    • ActionFlowCard 컴포넌트의 액션 색상도 모두 CSS 변수로 교체

  • ✅ ActionConfigStep.tsx:

    • bg-green-* → bg-success/10, text-success
    • bg-white → bg-background

  • ✅ ControlConditionStep.tsx:

    • text-green-600 → text-success
    • text-orange-500 → text-warning
    • text-blue-* → text-primary
    • bg-yellow-* → bg-warning/10
    • bg-white → bg-background

  • ✅ MultiActionConfigStep.tsx:

    • text-blue-* → text-primary
    • bg-yellow-* → bg-warning/10
    • text-yellow-* → text-warning
    • bg-white → bg-background
    • bg-gray-* → bg-muted

  • ✅ ScreenPreview.tsx:

    • border-gray-* → border-border
    • bg-white → bg-background
    • bg-gray-* → bg-muted
    • text-gray-* → text-muted-foreground

특수 케이스 패딩 사용 검토 완료

다음 파일들은 특수한 레이아웃 요구사항으로 인해 기본 패딩을 오버라이드하는 것이 정당함을 확인:

  1. DataflowVisualization.tsx: CardContent에 p-4 사용 (특수 레이아웃) - 내부 요소에 추가 패딩 적용
  2. ActionConfigStep.tsx: CardContent에 p-0 사용 (Tabs 전체 너비 필요) - 정당함
  3. ControlConditionStep.tsx: CardContent에 p-0 사용 (내부에 p-4 적용) - 정당함
  4. MultiActionConfigStep.tsx: CardContent에 p-4 사용 (특수 레이아웃) - 정당함

반응형 디자인 적용 완료

주요 컴포넌트들:

  • ✅ DataflowVisualization.tsx: Sankey 다이어그램 반응형 적용

    • 모바일: 세로 배치 (flex-col)
    • 데스크톱: 가로 배치 (sm:flex-row)
    • 패딩: p-4 sm:p-6
    • 텍스트 크기: text-xs sm:text-sm
    • 통계 카드: 모바일에서 세로 배치, 데스크톱에서 가로 배치

  • ✅ DashboardTopMenu.tsx: 상단 메뉴바 반응형 적용

    • 모바일: 세로 배치 (flex-col)
    • 데스크톱: 가로 배치 (sm:flex-row)
    • 버튼/Select: 모바일에서 전체 너비 (w-full sm:w-auto)
    • 텍스트 크기: text-base sm:text-lg

  • ✅ ActionConfigStep.tsx: 액션 설정 단계 반응형 적용

    • 탭 버튼: 모바일에서 텍스트 축약 (hidden sm:inline)
    • 패딩: p-3 sm:p-4
    • 네비게이션: 모바일에서 세로 배치 (flex-col sm:flex-row)

  • ✅ ControlConditionStep.tsx: 제어 조건 단계 반응형 적용

    • 패딩: p-3 sm:p-4
    • 네비게이션: 모바일에서 세로 배치

  • ✅ MultiActionConfigStep.tsx: 멀티 액션 설정 반응형 적용

    • 탭 버튼: 모바일에서 텍스트 축약
    • 패딩: p-3 sm:p-4
    • 네비게이션: 모바일에서 세로 배치

  • ✅ ScreenPreview.tsx: 화면 미리보기 반응형 적용

    • 헤더: 모바일에서 세로 배치 (flex-col sm:flex-row)
    • 버튼 그룹: 모바일에서 줄바꿈 (flex-wrap)