참고 문서

VertiTab 커스텀 테마 시스템 기술 참고 가이드.

공식 문서 링크

MUI 공식 리소스

• MUI 기본 테마 뷰어 - MUI 테마 구조와 기본값
• MUI 테마 커스터마이징 - 공식 가이드
• MUI 컴포넌트 API - 상세 API 문서

테마 구조 개요

기본 정보

{
  id: 'ultraviolet',
  name: 'Ultra Violet',
  description: 'Pantone Color of the Year 2018 - Ultra Violet with mysterious and creative purple tones',
  isBuiltIn: true,
  themeIndex: 17
}

컬러 스킴

colorSchemes: {
  light: {
    palette: {
      // 主要色调
      primary: { main: '#6B46C1' },
      secondary: { main: '#A855F7' },
      error: { main: '#DC2626' },
      warning: { main: '#D97706' },
      info: { main: '#2563EB' },
      success: { main: '#059669' },
      // 背景色
      background: {
        default: '#FEFBFF',
        paper: '#FAF7FF',
      },
      // 文字色
      text: {
        primary: '#1A1A1A',
        secondary: '#4A4A4A',
        disabled: '#9E9E9E',
      },
      // 动作色
      action: {
        active: '#5B21B6',
        hover: 'rgba(107, 70, 193, 0.08)',
        selected: 'rgba(107, 70, 193, 0.3)',
        focus: 'rgba(107, 70, 193, 0.16)',
      },
      divider: '#F3F0FF',
    },
  },
  dark: {
    // 深色模式配置...
  }
}

타이포그래피

typography: {
  htmlFontSize: 16,
  fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
  fontSize: 14,
  h1: {
    fontWeight: 500,
    fontSize: '1.5rem',
    lineHeight: 1.3
  },
  h4: {
    fontWeight: 400,
    fontSize: '0.875rem',
    lineHeight: 1.4
  },
  body1: {
    fontWeight: 400,
    fontSize: '0.875rem',
    lineHeight: 1.5
  },
  button: {
    fontWeight: 400,
    fontSize: '0.875rem',
    lineHeight: 1.75
  }
}

핵심 컴포넌트 예시

CSS 베이스라인

MuiCssBaseline: {
  defaultProps: {
    enableColorScheme: true
  },
  styleOverrides: {
    html: {
      fontSize: "16px"
    },
    body: {
      background: undefined,
      "-webkit-font-smoothing": 'antialiased',
      "-moz-osx-font-smoothing": 'grayscale'
    }
  }
}

리스트 항목 버튼

MuiListItemButton: {
  defaultProps: {
    dense: true,
    disableGutters: false,
    divider: false,
    disableRipple: false
  },
  styleOverrides: {
    root: {
      borderRadius: '6px',
      paddingTop: '4px',
      paddingRight: '8px',
      paddingBottom: '4px',
      paddingLeft: '8px',
      '&:hover': {
        backgroundColor: 'rgba(107, 70, 193, 0.08)',
        boxShadow: '0 2px 8px rgba(107, 70, 193, 0.15)',
        transform: 'translateY(-1px)'
      }
    }
  }
}

아이콘 버튼

MuiIconButton: {
  defaultProps: {
    disableRipple: false,
    disableFocusRipple: false,
    color: 'primary',
    size: 'small'
  },
  styleOverrides: {
    root: {
      padding: '4px',
      margin: 0,
      borderRadius: '6px',
      '&:hover': {
        backgroundColor: 'rgba(107, 70, 193, 0.08)',
        boxShadow: '0 2px 8px rgba(107, 70, 193, 0.2)',
      }
    }
  }
}

아이콘 컴포넌트

MuiIcon: {
  defaultProps: {
    fontSize: 'small',
    color: 'inherit'
  },
  styleOverrides: {
    root: {
      fontSize: '14px',
    }
  }
},
MuiSvgIcon: {
  defaultProps: {
    fontSize: 'small',
    color: 'inherit'
  },
  styleOverrides: {
    root: {
      fontSize: '14px'
    }
  }
}

아바타 컴포넌트

MuiAvatar: {
  defaultProps: {
    variant: 'rounded'
  },
  styleOverrides: {
    root: {
      width: '14px',
      height: '14px',
      fontSize: '14px',
    }
  }
}

메뉴 컴포넌트

MuiMenu: {
  defaultProps: {
    dense: true,
    disableAutoFocusItem: true,
  },
  styleOverrides: {
    paper: {
      borderRadius: '8px',
      paddingTop: '8px',
      paddingBottom: '8px',
      boxShadow: '0 8px 32px rgba(107, 70, 193, 0.15)',
      border: '1px solid rgba(107, 70, 193, 0.1)',
    }
  }
}

버튼 컴포넌트

MuiButton: {
  defaultProps: {
    color: 'primary',
    disableFocusRipple: false,
    disableRipple: false,
    size: 'small',
  },
  styleOverrides: {
    root: {
      borderRadius: '8px',
      '&:hover': {
        transform: 'translateY(-1px)',
        boxShadow: '0 4px 16px rgba(107, 70, 193, 0.25)'
      }
    }
  }
}

배경 설정 문법

단색

background: #6b46c1;
background: rgb(107, 70, 193);
background: rgba(107, 70, 193, 0.8);

그라데이션

background: linear-gradient(45deg, #6b46c1, #a855f7);
background: radial-gradient(circle, #6b46c1, #a855f7);

이미지

background: url("image.jpg") center/cover no-repeat;

테마 구성 팁

색상 일관성

• 使用相同的主色调系列
• 保持明暗模式的颜色对应
• 确保足够的对比度

컴포넌트 조화

• 统一的圆角设计（如 borderRadius: '6px'）
• 一致的间距模式（如 padding: '4px'）
• 协调的动画效果

성능 최적화

• 避免过度复杂的阴影和动画
• 使用 transform 而非改变布局属性
• 合理使用 transition 时长

자주 묻는 질문

테마가 적용되지 않음

1. 检查 JSON 语法是否正确
2. 确认主题已保存并应用
3. 清除浏览器缓存重新加载

스타일 충돌

1. 检查 CSS 特异性
2. 使用浏览器开发者工具调试
3. 确认组件名称拼写正确

성능 문제

1. 减少复杂的 CSS 动画
2. 优化背景图片大小
3. 限制自定义样式数量

관련 문서

• 테마 구성 수정 - 기본 구성 가이드
• 글꼴 크기 조정 - 타이포그래피 설정
• 배경 설정 - 배경 스타일 구성