superport/.cursor/rules/_ui_improvement.mdc

---
description : nothing
globs: 
alwaysApply : true
---


# UI 개선 작업 규칙

## **모델 정의 우선 확인**
- UI 화면에서 사용하는 모든 필드가 모델에 정의되어 있는지 확인
- enum 타입이 필요한 경우 적절히 정의하고 import
- nullable 타입은 UI에서 적절히 처리

## **컨트롤러 메서드 확인**
- 화면에서 호출하는 모든 메서드가 컨트롤러에 정의되어 있는지 확인
- 메서드 매개변수 개수와 타입이 일치하는지 확인
- 비동기 메서드의 경우 await 키워드 사용 확인

## **테마 시스템 활용**
- `ShadcnTheme.borderRadius` 대신 `ShadcnTheme.radiusMd` 사용
- 정의되지 않은 테마 속성 사용 금지
- 일관된 spacing 시스템 활용

## **테이블 레이아웃 최적화**
```dart
// ✅ DO: 전체 폭 활용과 행 높이 최적화
Expanded(
  child: Container(
    width: double.infinity,
    decoration: BoxDecoration(
      border: Border.all(color: ShadcnTheme.border),
      borderRadius: BorderRadius.circular(ShadcnTheme.radiusMd),
    ),
    child: Column(
      children: [
        // 테이블 헤더
        Container(
          padding: const EdgeInsets.symmetric(
            horizontal: ShadcnTheme.spacing4,
            vertical: ShadcnTheme.spacing3,
          ),
          decoration: BoxDecoration(
            color: ShadcnTheme.muted.withOpacity(0.3),
            border: Border(
              bottom: BorderSide(color: ShadcnTheme.border),
            ),
          ),
          // ... 헤더 내용
        ),
        // 테이블 데이터
        // ... 데이터 내용
      ],
    ),
  ),
)

// ❌ DON'T: ShadcnCard 사용으로 공간 낭비
ShadcnCard(
  child: Column(
    children: [
      Container(
        padding: const EdgeInsets.all(ShadcnTheme.spacing4),
        // ... 내용
      ),
    ],
  ),
)
```

## **Null Safety 처리**
```dart
// ✅ DO: nullable 타입 적절히 처리
onPressed: item.id != null ? () => deleteItem(item.id!) : null,

// ❌ DON'T: nullable 타입을 non-nullable로 직접 전달
onPressed: () => deleteItem(item.id), // item.id가 int?인 경우 오류
```

## **사용자 역할/상태 처리**
```dart
// ✅ DO: 실제 모델 필드 기반 처리
Widget _buildUserRoleBadge(String role) {
  switch (role) {
    case 'S':
      return ShadcnBadge(text: '관리자', variant: ShadcnBadgeVariant.destructive);
    case 'M':
      return ShadcnBadge(text: '멤버', variant: ShadcnBadgeVariant.primary);
    default:
      return ShadcnBadge(text: '사용자', variant: ShadcnBadgeVariant.outline);
  }
}

// ❌ DON'T: 정의되지 않은 enum 사용
Widget _buildUserRoleBadge(UserRole role) {
  switch (role) {
    case UserRole.admin: // UserRole이 정의되지 않은 경우 오류
      // ...
  }
}
```

## **렌더링 오류 방지**
- 복잡한 위젯 대신 안정적인 Container 사용
- 데이터 없음 상태에 대한 적절한 UI 제공
- 긴 텍스트는 overflow 처리 (`TextOverflow.ellipsis`)

## **파일 구조 완성도 확인**
- 모든 괄호, 중괄호가 올바르게 닫혔는지 확인
- 필요한 import 문이 모두 포함되었는지 확인
- Dart 문법 규칙 준수

## **성능 최적화**
- 테이블 행 높이 최적화: `spacing3` 사용
- 불필요한 버튼 제거 (새로고침 등)
- 중복 제목 제거
- 공간 효율성 극대화

이 규칙들을 따르면 UI 개선 작업 시 발생할 수 있는 대부분의 문제들을 사전에 방지할 수 있습니다.
description:
globs:
alwaysApply: false
---